跳转至

whiteboards

feishu.board.whiteboards

BoardNamespace

Bases: Namespace

画板（Board）接口命名空间。

封装飞书画板（Board）相关的服务端接口，包括获取画板主题、列举画板内的全部节点， 以及将整块画板导出为图片等能力。画板由若干节点（node）组成，节点是画板内容的最小结构单元。

通常无需直接实例化，应通过客户端的 client.board 访问。

飞书文档

画板概述

源代码位于： feishu/board/whiteboards.py
Python
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
class BoardNamespace(Namespace):
    r"""
    画板（Board）接口命名空间。

    封装飞书画板（Board）相关的服务端接口，包括获取画板主题、列举画板内的全部节点，
    以及将整块画板导出为图片等能力。画板由若干节点（node）组成，节点是画板内容的最小结构单元。

    通常无需直接实例化，应通过客户端的 `client.board` 访问。

    飞书文档:
        [画板概述](https://open.feishu.cn/document/server-docs/docs/board-v1/overview)
    """

    async def download_as_image(self, whiteboard_id: str) -> bytes:
        r"""
        下载画板为图片。

        将整块画板渲染并导出为图片，返回图片的原始字节内容（通常为 PNG）。

        Args:
            whiteboard_id: 画板的唯一标识。

        Returns:
            画板图片的原始字节内容。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [下载为图片](https://open.feishu.cn/document/docs/board-v1/whiteboard/download_as_image)
            参见 [feishu.board.whiteboards.BoardNamespace.list_nodes][]。

        Examples:
            >>> import asyncio
            >>> async def main():
            ...     async with FeishuClient("cli_xxx", "secret") as client:
            ...         return await client.board.download_as_image("wb_abc")
            >>> asyncio.run(main())  # doctest: +SKIP
            b'\\x89PNG...'
        """
        return await self._client.download(f"board/v1/whiteboards/{quote_segment(whiteboard_id)}/download_as_image")

    async def get_theme(self, whiteboard_id: str) -> NestedDict:
        r"""
        获取画板主题。

        返回画板当前使用的主题信息。该接口对应开放平台的「获取画板主题」能力，响应数据
        含 `theme` 字段（取值如 `classic`、`minimalist_gray`、`default` 等）。

        Args:
            whiteboard_id: 画板的唯一标识。

        Returns:
            画板主题数据，含 `theme` 字段（画板当前主题的标识）。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [获取画板主题](https://open.feishu.cn/document/docs/board-v1/whiteboard/theme)
            参见 [feishu.board.whiteboards.BoardNamespace.list_nodes][]。

        Examples:
            >>> await client.board.get_theme("wb_abc")  # doctest:+SKIP
            {'theme': 'classic'}
        """
        return await self._request_data("GET", f"board/v1/whiteboards/{quote_segment(whiteboard_id)}/theme")

    async def list_nodes(self, whiteboard_id: str, *, user_id_type: str | None = None) -> list[NestedDict]:
        r"""
        获取画板内的所有节点。

        一次性返回画板内的全部节点（该接口不分页），节点以 `id`、`type`、`parent_id`、
        `children` 以及对应类型的内容字段（如 `text`、`image`、`composite_shape` 等）描述。

        Args:
            whiteboard_id: 画板的唯一标识。
            user_id_type: 返回数据中的用户 ID 类型，如 `open_id`、`union_id`、`user_id`；
                为空时使用接口默认值。

        Returns:
            画板节点数据列表（取自响应数据的 `nodes` 字段）；画板为空时返回空列表。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [获取所有节点](https://open.feishu.cn/document/docs/board-v1/whiteboard-node/list)
            参见 [feishu.board.whiteboards.BoardNamespace.get_theme][]。

        Examples:
            >>> await client.board.list_nodes("wb_abc")  # doctest:+SKIP
            [{'id': 'n1', 'type': 'composite_shape', ...}, {'id': 'n2', 'type': 'text', ...}]
        """
        params = {"user_id_type": user_id_type}
        envelope = await self._client.request(
            "GET", f"board/v1/whiteboards/{quote_segment(whiteboard_id)}/nodes", params=params
        )
        return _data(envelope).get("nodes", []) or []

download_as_image async

Python
download_as_image(whiteboard_id: str) -> bytes

下载画板为图片。

将整块画板渲染并导出为图片，返回图片的原始字节内容（通常为 PNG）。

参数：

名称 类型 描述 默认
whiteboard_id
str

画板的唯一标识。

 必需

返回：

类型 描述
bytes

画板图片的原始字节内容。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

下载为图片 参见 feishu.board.whiteboards.BoardNamespace.list_nodes。

示例：

Python Console Session
1
2
3
4
5
6
>>> import asyncio
>>> async def main():
...     async with FeishuClient("cli_xxx", "secret") as client:
...         return await client.board.download_as_image("wb_abc")
>>> asyncio.run(main())
b'\\x89PNG...'
源代码位于： feishu/board/whiteboards.py
Python
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
async def download_as_image(self, whiteboard_id: str) -> bytes:
    r"""
    下载画板为图片。

    将整块画板渲染并导出为图片，返回图片的原始字节内容（通常为 PNG）。

    Args:
        whiteboard_id: 画板的唯一标识。

    Returns:
        画板图片的原始字节内容。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [下载为图片](https://open.feishu.cn/document/docs/board-v1/whiteboard/download_as_image)
        参见 [feishu.board.whiteboards.BoardNamespace.list_nodes][]。

    Examples:
        >>> import asyncio
        >>> async def main():
        ...     async with FeishuClient("cli_xxx", "secret") as client:
        ...         return await client.board.download_as_image("wb_abc")
        >>> asyncio.run(main())  # doctest: +SKIP
        b'\\x89PNG...'
    """
    return await self._client.download(f"board/v1/whiteboards/{quote_segment(whiteboard_id)}/download_as_image")

get_theme async

Python
get_theme(whiteboard_id: str) -> NestedDict

获取画板主题。

返回画板当前使用的主题信息。该接口对应开放平台的「获取画板主题」能力，响应数据 含 theme 字段（取值如 classic、minimalist_gray、default 等）。

参数：

名称 类型 描述 默认
whiteboard_id
str

画板的唯一标识。

 必需

返回：

类型 描述
NestedDict

画板主题数据，含 theme 字段（画板当前主题的标识）。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

获取画板主题 参见 feishu.board.whiteboards.BoardNamespace.list_nodes。

示例：

Python Console Session
1
2
>>> await client.board.get_theme("wb_abc")
{'theme': 'classic'}
源代码位于： feishu/board/whiteboards.py
Python
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
async def get_theme(self, whiteboard_id: str) -> NestedDict:
    r"""
    获取画板主题。

    返回画板当前使用的主题信息。该接口对应开放平台的「获取画板主题」能力，响应数据
    含 `theme` 字段（取值如 `classic`、`minimalist_gray`、`default` 等）。

    Args:
        whiteboard_id: 画板的唯一标识。

    Returns:
        画板主题数据，含 `theme` 字段（画板当前主题的标识）。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [获取画板主题](https://open.feishu.cn/document/docs/board-v1/whiteboard/theme)
        参见 [feishu.board.whiteboards.BoardNamespace.list_nodes][]。

    Examples:
        >>> await client.board.get_theme("wb_abc")  # doctest:+SKIP
        {'theme': 'classic'}
    """
    return await self._request_data("GET", f"board/v1/whiteboards/{quote_segment(whiteboard_id)}/theme")

list_nodes async

Python
list_nodes(whiteboard_id: str, *, user_id_type: str | None = None) -> list[NestedDict]

获取画板内的所有节点。

一次性返回画板内的全部节点（该接口不分页），节点以 id、type、parent_id、 children 以及对应类型的内容字段（如 text、image、composite_shape 等）描述。

参数：

名称 类型 描述 默认
whiteboard_id
str

画板的唯一标识。

 必需
user_id_type
str | None

返回数据中的用户 ID 类型，如 open_id、union_id、user_id； 为空时使用接口默认值。

 None

返回：

类型 描述
list[NestedDict]

画板节点数据列表（取自响应数据的 nodes 字段）；画板为空时返回空列表。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

获取所有节点 参见 feishu.board.whiteboards.BoardNamespace.get_theme。

示例：

Python Console Session
1
2
>>> await client.board.list_nodes("wb_abc")
[{'id': 'n1', 'type': 'composite_shape', ...}, {'id': 'n2', 'type': 'text', ...}]
源代码位于： feishu/board/whiteboards.py
Python
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
async def list_nodes(self, whiteboard_id: str, *, user_id_type: str | None = None) -> list[NestedDict]:
    r"""
    获取画板内的所有节点。

    一次性返回画板内的全部节点（该接口不分页），节点以 `id`、`type`、`parent_id`、
    `children` 以及对应类型的内容字段（如 `text`、`image`、`composite_shape` 等）描述。

    Args:
        whiteboard_id: 画板的唯一标识。
        user_id_type: 返回数据中的用户 ID 类型，如 `open_id`、`union_id`、`user_id`；
            为空时使用接口默认值。

    Returns:
        画板节点数据列表（取自响应数据的 `nodes` 字段）；画板为空时返回空列表。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [获取所有节点](https://open.feishu.cn/document/docs/board-v1/whiteboard-node/list)
        参见 [feishu.board.whiteboards.BoardNamespace.get_theme][]。

    Examples:
        >>> await client.board.list_nodes("wb_abc")  # doctest:+SKIP
        [{'id': 'n1', 'type': 'composite_shape', ...}, {'id': 'n2', 'type': 'text', ...}]
    """
    params = {"user_id_type": user_id_type}
    envelope = await self._client.request(
        "GET", f"board/v1/whiteboards/{quote_segment(whiteboard_id)}/nodes", params=params
    )
    return _data(envelope).get("nodes", []) or []