跳转至

documents

feishu.docx.documents

DocxNamespace

Bases: Namespace

新版文档（Docx）接口命名空间。

封装飞书云文档（Docx）相关的服务端接口，包括创建文档、获取文档元信息与纯文本内容， 以及获取、追加、更新文档块（block）等能力。文档由若干块组成，块是文档内容的最小结构单元。

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

飞书文档

文档概述

源代码位于： feishu/docx/documents.py
Python
 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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
class DocxNamespace(Namespace):
    r"""
    新版文档（Docx）接口命名空间。

    封装飞书云文档（Docx）相关的服务端接口，包括创建文档、获取文档元信息与纯文本内容，
    以及获取、追加、更新文档块（block）等能力。文档由若干块组成，块是文档内容的最小结构单元。

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

    飞书文档:
        [文档概述](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/intro)
    """

    async def append_blocks(
        self,
        document_id: str,
        children: list[dict[str, Any]],
        *,
        block_id: str | None = None,
        index: int | None = None,
    ) -> NestedDict:
        r"""
        在指定块下创建子块。

        将 `children` 作为子块追加到目标块下；`block_id` 为空时以文档根块（即 `document_id`）
        为父块。`index` 控制插入位置（自 0 起），为空时追加到末尾。仅将显式传入的字段写入请求体。

        Args:
            document_id: 文档的唯一标识。
            children: 待创建的子块对象列表，每个元素描述一个块（含 `block_type` 等）。
            block_id: 父块的唯一标识；为空时使用文档根块 `document_id`。
            index: 插入位置（自 0 起）；为空时追加到子块末尾。

        Returns:
            创建结果数据，含新建的 `children` 列表与文档 `document_revision_id` 等。

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

        飞书文档:
            [创建块](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block-children/create)
            参见 [feishu.docx.documents.DocxNamespace.patch_block][]。

        Examples:
            >>> blocks = [{"block_type": 2, "text": {"elements": [{"text_run": {"content": "hi"}}]}}]
            >>> await client.docx.append_blocks("doxcabc", blocks)  # doctest:+SKIP
            {'children': [{'block_id': 'blk_new', 'block_type': 2, ...}], 'document_revision_id': 13}
        """
        parent = block_id if block_id is not None else document_id
        body: dict[str, Any] = {"children": children}
        if index is not None:
            body["index"] = index
        return await self._request_data(
            "POST",
            f"docx/v1/documents/{quote_segment(document_id)}/blocks/{quote_segment(parent)}/children",
            json=body,
        )

    async def batch_update_blocks(self, document_id: str, requests: list[dict[str, Any]]) -> NestedDict:
        r"""
        批量更新文档块。

        在一次请求中对多个块执行更新操作，`requests` 为更新操作列表，每个元素与
        [feishu.docx.documents.DocxNamespace.patch_block][] 的 `update` 同构，并额外携带
        其作用的 `block_id`。

        Args:
            document_id: 文档的唯一标识。
            requests: 更新操作列表，每个元素形如
                `{"block_id": "blk2", "update_text_elements": {...}}`。

        Returns:
            批量更新结果数据，含更新后的 `blocks` 列表与文档 `document_revision_id` 等。

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

        飞书文档:
            [批量更新块的内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/batch_update)
            参见 [feishu.docx.documents.DocxNamespace.patch_block][]。

        Examples:
            >>> reqs = [{"block_id": "blk2", "update_text_elements": {"elements": []}}]
            >>> await client.docx.batch_update_blocks("doxcabc", reqs)  # doctest:+SKIP
            {'blocks': [{'block_id': 'blk2', ...}], 'document_revision_id': 15}
        """
        return await self._request_data(
            "PATCH",
            f"docx/v1/documents/{quote_segment(document_id)}/blocks/batch_update",
            json={"requests": requests},
        )

    async def create(self, title: str, *, folder_token: str | None = None) -> NestedDict:
        r"""
        创建文档。

        在指定文件夹（或用户云空间根目录）下创建一篇新的空白文档。仅将显式传入的字段
        写入请求体，未设置的字段会被省略。

        Args:
            title: 文档标题。
            folder_token: 目标文件夹 token；为空时创建在云空间根目录下。

        Returns:
            创建后的文档数据，含 `document` 字段（其中含 `document_id`、`revision_id`、`title`）。

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

        飞书文档:
            [创建文档](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/create)
            参见 [feishu.docx.documents.DocxNamespace.get][]。

        Examples:
            >>> await client.docx.create(title="My Doc")  # doctest:+SKIP
            {'document': {'document_id': 'doxcabc', 'revision_id': 1, 'title': 'My Doc'}}
        """
        body = {"title": title}
        if folder_token is not None:
            body["folder_token"] = folder_token
        return await self._request_data("POST", "docx/v1/documents", json=body)

    async def get(self, document_id: str) -> NestedDict:
        r"""
        获取文档基本信息。

        Args:
            document_id: 文档的唯一标识。

        Returns:
            文档元信息数据，含 `document` 字段（其中含 `document_id`、`revision_id`、`title`）。

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

        飞书文档:
            [获取文档基本信息](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/get)
            参见 [feishu.docx.documents.DocxNamespace.raw_content][]。

        Examples:
            >>> await client.docx.get("doxcabc")  # doctest:+SKIP
            {'document': {'document_id': 'doxcabc', 'revision_id': 12, 'title': 'My Doc'}}
        """
        return await self._request_data("GET", f"docx/v1/documents/{quote_segment(document_id)}")

    async def get_block(self, document_id: str, block_id: str) -> NestedDict:
        r"""
        获取指定块的内容。

        Args:
            document_id: 文档的唯一标识。
            block_id: 块的唯一标识。

        Returns:
            块数据，含 `block_id`、`block_type`、`parent_id` 及对应类型的内容字段。

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

        飞书文档:
            [获取块的内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/get)
            参见 [feishu.docx.documents.DocxNamespace.list_blocks][]。

        Examples:
            >>> await client.docx.get_block("doxcabc", "blk2")  # doctest:+SKIP
            {'block_id': 'blk2', 'block_type': 2, 'parent_id': 'doxcabc', ...}
        """
        return await self._request_data(
            "GET", f"docx/v1/documents/{quote_segment(document_id)}/blocks/{quote_segment(block_id)}"
        )

    async def list_blocks(
        self, document_id: str, *, page_size: int = 500, max_items: int | None = None
    ) -> list[NestedDict]:
        r"""
        获取文档所有块。

        自动翻页并将各页结果拼接为单个列表返回，返回的块按文档顺序排列（含各级嵌套块）。
        `page_size` 会被限制在 [feishu.docx.documents.MAX_BLOCK_PAGE_SIZE][] 以内。

        Args:
            document_id: 文档的唯一标识。
            page_size: 每页条数，默认为 500，超过上限时按上限截断。
            max_items: 最多返回的条数；为空表示返回全部。

        Returns:
            文档块数据列表，每个元素含 `block_id`、`block_type`、`parent_id` 等字段。

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

        飞书文档:
            [获取文档所有块](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/list)
            参见 [feishu.docx.documents.DocxNamespace.get_block][]。

        Examples:
            >>> await client.docx.list_blocks("doxcabc")  # doctest:+SKIP
            [{'block_id': 'doxcabc', 'block_type': 1, ...}, {'block_id': 'blk2', 'block_type': 2, ...}]
        """

        # 不走 client.paginate_get：块列表上限为 MAX_BLOCK_PAGE_SIZE=500，
        # 而 paginate_get 会将 page_size 截断至通用的 MAX_PAGE_SIZE=50，对块列表过小，故保留手写翻页闭包。
        async def fetch(page_token: str | None) -> NestedDict:
            params = {
                "page_size": min(page_size, MAX_BLOCK_PAGE_SIZE),
                "page_token": page_token,
            }
            return await self._client.request(
                "GET", f"docx/v1/documents/{quote_segment(document_id)}/blocks", params=params
            )

        return await paginate(fetch, max_items=max_items)

    async def patch_block(self, document_id: str, block_id: str, update: dict[str, Any]) -> NestedDict:
        r"""
        更新指定块的内容。

        `update` 是描述更新操作的请求体，原样作为 JSON 发送，常见键包括
        `update_text_elements`、`update_text_style`、`update_table_property` 等。

        Args:
            document_id: 文档的唯一标识。
            block_id: 待更新块的唯一标识。
            update: 更新操作请求体，例如 `{"update_text_elements": {"elements": [...]}}`。

        Returns:
            更新后的块数据及文档 `document_revision_id` 等。

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

        飞书文档:
            [更新块的内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/patch)
            参见 [feishu.docx.documents.DocxNamespace.batch_update_blocks][]。

        Examples:
            >>> update = {"update_text_elements": {"elements": [{"text_run": {"content": "new"}}]}}
            >>> await client.docx.patch_block("doxcabc", "blk2", update)  # doctest:+SKIP
            {'block': {'block_id': 'blk2', 'block_type': 2, ...}, 'document_revision_id': 14}
        """
        return await self._request_data(
            "PATCH", f"docx/v1/documents/{quote_segment(document_id)}/blocks/{quote_segment(block_id)}", json=update
        )

    async def raw_content(self, document_id: str, *, lang: int | None = None) -> str:
        r"""
        获取文档纯文本内容。

        返回文档去除格式后的纯文本，便于做检索、摘要等文本处理。`lang` 用于控制
        文档中 @ 提及（如人员、文档）等内容的展示语言。

        Args:
            document_id: 文档的唯一标识。
            lang: 内容语言，`0` 默认语言、`1` 中文、`2` 英文；为空时使用接口默认值。

        Returns:
            文档的纯文本内容字符串（取自响应数据的 `content` 字段）。

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

        飞书文档:
            [获取文档纯文本内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/raw_content)
            参见 [feishu.docx.documents.DocxNamespace.list_blocks][]。

        Examples:
            >>> await client.docx.raw_content("doxcabc")  # doctest:+SKIP
            'Hello world\n'
        """
        params = {"lang": lang}
        envelope = await self._client.request(
            "GET", f"docx/v1/documents/{quote_segment(document_id)}/raw_content", params=params
        )
        return _data(envelope)["content"]

append_blocks async

Python
append_blocks(document_id: str, children: list[dict[str, Any]], *, block_id: str | None = None, index: int | None = None) -> NestedDict

在指定块下创建子块。

将 children 作为子块追加到目标块下；block_id 为空时以文档根块（即 document_id） 为父块。index 控制插入位置（自 0 起），为空时追加到末尾。仅将显式传入的字段写入请求体。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需
children
list[dict[str, Any]]

待创建的子块对象列表，每个元素描述一个块（含 block_type 等）。

 必需
block_id
str | None

父块的唯一标识；为空时使用文档根块 document_id。

 None
index
int | None

插入位置（自 0 起）；为空时追加到子块末尾。

 None

返回：

类型 描述
NestedDict

创建结果数据，含新建的 children 列表与文档 document_revision_id 等。

引发：

类型 描述
FeishuError

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

创建块 参见 feishu.docx.documents.DocxNamespace.patch_block。

示例：

Python Console Session
1
2
3
>>> blocks = [{"block_type": 2, "text": {"elements": [{"text_run": {"content": "hi"}}]}}]
>>> await client.docx.append_blocks("doxcabc", blocks)
{'children': [{'block_id': 'blk_new', 'block_type': 2, ...}], 'document_revision_id': 13}
源代码位于： feishu/docx/documents.py
Python
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
async def append_blocks(
    self,
    document_id: str,
    children: list[dict[str, Any]],
    *,
    block_id: str | None = None,
    index: int | None = None,
) -> NestedDict:
    r"""
    在指定块下创建子块。

    将 `children` 作为子块追加到目标块下；`block_id` 为空时以文档根块（即 `document_id`）
    为父块。`index` 控制插入位置（自 0 起），为空时追加到末尾。仅将显式传入的字段写入请求体。

    Args:
        document_id: 文档的唯一标识。
        children: 待创建的子块对象列表，每个元素描述一个块（含 `block_type` 等）。
        block_id: 父块的唯一标识；为空时使用文档根块 `document_id`。
        index: 插入位置（自 0 起）；为空时追加到子块末尾。

    Returns:
        创建结果数据，含新建的 `children` 列表与文档 `document_revision_id` 等。

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

    飞书文档:
        [创建块](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block-children/create)
        参见 [feishu.docx.documents.DocxNamespace.patch_block][]。

    Examples:
        >>> blocks = [{"block_type": 2, "text": {"elements": [{"text_run": {"content": "hi"}}]}}]
        >>> await client.docx.append_blocks("doxcabc", blocks)  # doctest:+SKIP
        {'children': [{'block_id': 'blk_new', 'block_type': 2, ...}], 'document_revision_id': 13}
    """
    parent = block_id if block_id is not None else document_id
    body: dict[str, Any] = {"children": children}
    if index is not None:
        body["index"] = index
    return await self._request_data(
        "POST",
        f"docx/v1/documents/{quote_segment(document_id)}/blocks/{quote_segment(parent)}/children",
        json=body,
    )

batch_update_blocks async

Python
batch_update_blocks(document_id: str, requests: list[dict[str, Any]]) -> NestedDict

批量更新文档块。

在一次请求中对多个块执行更新操作，requests 为更新操作列表，每个元素与 feishu.docx.documents.DocxNamespace.patch_block 的 update 同构，并额外携带 其作用的 block_id。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需
requests
list[dict[str, Any]]

更新操作列表，每个元素形如 {"block_id": "blk2", "update_text_elements": {...}}。

 必需

返回：

类型 描述
NestedDict

批量更新结果数据，含更新后的 blocks 列表与文档 document_revision_id 等。

引发：

类型 描述
FeishuError

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

批量更新块的内容 参见 feishu.docx.documents.DocxNamespace.patch_block。

示例：

Python Console Session
1
2
3
>>> reqs = [{"block_id": "blk2", "update_text_elements": {"elements": []}}]
>>> await client.docx.batch_update_blocks("doxcabc", reqs)
{'blocks': [{'block_id': 'blk2', ...}], 'document_revision_id': 15}
源代码位于： feishu/docx/documents.py
Python
 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
async def batch_update_blocks(self, document_id: str, requests: list[dict[str, Any]]) -> NestedDict:
    r"""
    批量更新文档块。

    在一次请求中对多个块执行更新操作，`requests` 为更新操作列表，每个元素与
    [feishu.docx.documents.DocxNamespace.patch_block][] 的 `update` 同构，并额外携带
    其作用的 `block_id`。

    Args:
        document_id: 文档的唯一标识。
        requests: 更新操作列表，每个元素形如
            `{"block_id": "blk2", "update_text_elements": {...}}`。

    Returns:
        批量更新结果数据，含更新后的 `blocks` 列表与文档 `document_revision_id` 等。

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

    飞书文档:
        [批量更新块的内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/batch_update)
        参见 [feishu.docx.documents.DocxNamespace.patch_block][]。

    Examples:
        >>> reqs = [{"block_id": "blk2", "update_text_elements": {"elements": []}}]
        >>> await client.docx.batch_update_blocks("doxcabc", reqs)  # doctest:+SKIP
        {'blocks': [{'block_id': 'blk2', ...}], 'document_revision_id': 15}
    """
    return await self._request_data(
        "PATCH",
        f"docx/v1/documents/{quote_segment(document_id)}/blocks/batch_update",
        json={"requests": requests},
    )

create async

Python
create(title: str, *, folder_token: str | None = None) -> NestedDict

创建文档。

在指定文件夹（或用户云空间根目录）下创建一篇新的空白文档。仅将显式传入的字段 写入请求体，未设置的字段会被省略。

参数：

名称 类型 描述 默认
title
str

文档标题。

 必需
folder_token
str | None

目标文件夹 token；为空时创建在云空间根目录下。

 None

返回：

类型 描述
NestedDict

创建后的文档数据，含 document 字段（其中含 document_id、revision_id、title）。

引发：

类型 描述
FeishuError

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

创建文档 参见 feishu.docx.documents.DocxNamespace.get。

示例：

Python Console Session
1
2
>>> await client.docx.create(title="My Doc")
{'document': {'document_id': 'doxcabc', 'revision_id': 1, 'title': 'My Doc'}}
源代码位于： feishu/docx/documents.py
Python
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
async def create(self, title: str, *, folder_token: str | None = None) -> NestedDict:
    r"""
    创建文档。

    在指定文件夹（或用户云空间根目录）下创建一篇新的空白文档。仅将显式传入的字段
    写入请求体，未设置的字段会被省略。

    Args:
        title: 文档标题。
        folder_token: 目标文件夹 token；为空时创建在云空间根目录下。

    Returns:
        创建后的文档数据，含 `document` 字段（其中含 `document_id`、`revision_id`、`title`）。

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

    飞书文档:
        [创建文档](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/create)
        参见 [feishu.docx.documents.DocxNamespace.get][]。

    Examples:
        >>> await client.docx.create(title="My Doc")  # doctest:+SKIP
        {'document': {'document_id': 'doxcabc', 'revision_id': 1, 'title': 'My Doc'}}
    """
    body = {"title": title}
    if folder_token is not None:
        body["folder_token"] = folder_token
    return await self._request_data("POST", "docx/v1/documents", json=body)

get async

Python
get(document_id: str) -> NestedDict

获取文档基本信息。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需

返回：

类型 描述
NestedDict

文档元信息数据，含 document 字段（其中含 document_id、revision_id、title）。

引发：

类型 描述
FeishuError

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

获取文档基本信息 参见 feishu.docx.documents.DocxNamespace.raw_content。

示例：

Python Console Session
1
2
>>> await client.docx.get("doxcabc")
{'document': {'document_id': 'doxcabc', 'revision_id': 12, 'title': 'My Doc'}}
源代码位于： feishu/docx/documents.py
Python
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
async def get(self, document_id: str) -> NestedDict:
    r"""
    获取文档基本信息。

    Args:
        document_id: 文档的唯一标识。

    Returns:
        文档元信息数据，含 `document` 字段（其中含 `document_id`、`revision_id`、`title`）。

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

    飞书文档:
        [获取文档基本信息](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/get)
        参见 [feishu.docx.documents.DocxNamespace.raw_content][]。

    Examples:
        >>> await client.docx.get("doxcabc")  # doctest:+SKIP
        {'document': {'document_id': 'doxcabc', 'revision_id': 12, 'title': 'My Doc'}}
    """
    return await self._request_data("GET", f"docx/v1/documents/{quote_segment(document_id)}")

get_block async

Python
get_block(document_id: str, block_id: str) -> NestedDict

获取指定块的内容。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需
block_id
str

块的唯一标识。

 必需

返回：

类型 描述
NestedDict

块数据，含 block_id、block_type、parent_id 及对应类型的内容字段。

引发：

类型 描述
FeishuError

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

获取块的内容 参见 feishu.docx.documents.DocxNamespace.list_blocks。

示例：

Python Console Session
1
2
>>> await client.docx.get_block("doxcabc", "blk2")
{'block_id': 'blk2', 'block_type': 2, 'parent_id': 'doxcabc', ...}
源代码位于： feishu/docx/documents.py
Python
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
async def get_block(self, document_id: str, block_id: str) -> NestedDict:
    r"""
    获取指定块的内容。

    Args:
        document_id: 文档的唯一标识。
        block_id: 块的唯一标识。

    Returns:
        块数据，含 `block_id`、`block_type`、`parent_id` 及对应类型的内容字段。

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

    飞书文档:
        [获取块的内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/get)
        参见 [feishu.docx.documents.DocxNamespace.list_blocks][]。

    Examples:
        >>> await client.docx.get_block("doxcabc", "blk2")  # doctest:+SKIP
        {'block_id': 'blk2', 'block_type': 2, 'parent_id': 'doxcabc', ...}
    """
    return await self._request_data(
        "GET", f"docx/v1/documents/{quote_segment(document_id)}/blocks/{quote_segment(block_id)}"
    )

list_blocks async

Python
list_blocks(document_id: str, *, page_size: int = 500, max_items: int | None = None) -> list[NestedDict]

获取文档所有块。

自动翻页并将各页结果拼接为单个列表返回，返回的块按文档顺序排列（含各级嵌套块）。 page_size 会被限制在 [feishu.docx.documents.MAX_BLOCK_PAGE_SIZE][] 以内。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需
page_size
int

每页条数，默认为 500，超过上限时按上限截断。

 500
max_items
int | None

最多返回的条数；为空表示返回全部。

 None

返回：

类型 描述
list[NestedDict]

文档块数据列表，每个元素含 block_id、block_type、parent_id 等字段。

引发：

类型 描述
FeishuError

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

获取文档所有块 参见 feishu.docx.documents.DocxNamespace.get_block。

示例：

Python Console Session
1
2
>>> await client.docx.list_blocks("doxcabc")
[{'block_id': 'doxcabc', 'block_type': 1, ...}, {'block_id': 'blk2', 'block_type': 2, ...}]
源代码位于： feishu/docx/documents.py
Python
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
async def list_blocks(
    self, document_id: str, *, page_size: int = 500, max_items: int | None = None
) -> list[NestedDict]:
    r"""
    获取文档所有块。

    自动翻页并将各页结果拼接为单个列表返回，返回的块按文档顺序排列（含各级嵌套块）。
    `page_size` 会被限制在 [feishu.docx.documents.MAX_BLOCK_PAGE_SIZE][] 以内。

    Args:
        document_id: 文档的唯一标识。
        page_size: 每页条数，默认为 500，超过上限时按上限截断。
        max_items: 最多返回的条数；为空表示返回全部。

    Returns:
        文档块数据列表，每个元素含 `block_id`、`block_type`、`parent_id` 等字段。

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

    飞书文档:
        [获取文档所有块](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/list)
        参见 [feishu.docx.documents.DocxNamespace.get_block][]。

    Examples:
        >>> await client.docx.list_blocks("doxcabc")  # doctest:+SKIP
        [{'block_id': 'doxcabc', 'block_type': 1, ...}, {'block_id': 'blk2', 'block_type': 2, ...}]
    """

    # 不走 client.paginate_get：块列表上限为 MAX_BLOCK_PAGE_SIZE=500，
    # 而 paginate_get 会将 page_size 截断至通用的 MAX_PAGE_SIZE=50，对块列表过小，故保留手写翻页闭包。
    async def fetch(page_token: str | None) -> NestedDict:
        params = {
            "page_size": min(page_size, MAX_BLOCK_PAGE_SIZE),
            "page_token": page_token,
        }
        return await self._client.request(
            "GET", f"docx/v1/documents/{quote_segment(document_id)}/blocks", params=params
        )

    return await paginate(fetch, max_items=max_items)

patch_block async

Python
patch_block(document_id: str, block_id: str, update: dict[str, Any]) -> NestedDict

更新指定块的内容。

update 是描述更新操作的请求体，原样作为 JSON 发送，常见键包括 update_text_elements、update_text_style、update_table_property 等。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需
block_id
str

待更新块的唯一标识。

 必需
update
dict[str, Any]

更新操作请求体，例如 {"update_text_elements": {"elements": [...]}}。

 必需

返回：

类型 描述
NestedDict

更新后的块数据及文档 document_revision_id 等。

引发：

类型 描述
FeishuError

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

更新块的内容 参见 feishu.docx.documents.DocxNamespace.batch_update_blocks。

示例：

Python Console Session
1
2
3
>>> update = {"update_text_elements": {"elements": [{"text_run": {"content": "new"}}]}}
>>> await client.docx.patch_block("doxcabc", "blk2", update)
{'block': {'block_id': 'blk2', 'block_type': 2, ...}, 'document_revision_id': 14}
源代码位于： feishu/docx/documents.py
Python
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
async def patch_block(self, document_id: str, block_id: str, update: dict[str, Any]) -> NestedDict:
    r"""
    更新指定块的内容。

    `update` 是描述更新操作的请求体，原样作为 JSON 发送，常见键包括
    `update_text_elements`、`update_text_style`、`update_table_property` 等。

    Args:
        document_id: 文档的唯一标识。
        block_id: 待更新块的唯一标识。
        update: 更新操作请求体，例如 `{"update_text_elements": {"elements": [...]}}`。

    Returns:
        更新后的块数据及文档 `document_revision_id` 等。

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

    飞书文档:
        [更新块的内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/patch)
        参见 [feishu.docx.documents.DocxNamespace.batch_update_blocks][]。

    Examples:
        >>> update = {"update_text_elements": {"elements": [{"text_run": {"content": "new"}}]}}
        >>> await client.docx.patch_block("doxcabc", "blk2", update)  # doctest:+SKIP
        {'block': {'block_id': 'blk2', 'block_type': 2, ...}, 'document_revision_id': 14}
    """
    return await self._request_data(
        "PATCH", f"docx/v1/documents/{quote_segment(document_id)}/blocks/{quote_segment(block_id)}", json=update
    )

raw_content async

Python
raw_content(document_id: str, *, lang: int | None = None) -> str

获取文档纯文本内容。

返回文档去除格式后的纯文本，便于做检索、摘要等文本处理。lang 用于控制 文档中 @ 提及（如人员、文档）等内容的展示语言。

参数：

名称 类型 描述 默认
document_id
str

文档的唯一标识。

 必需
lang
int | None

内容语言，0 默认语言、1 中文、2 英文；为空时使用接口默认值。

 None

返回：

类型 描述
str

文档的纯文本内容字符串（取自响应数据的 content 字段）。

引发：

类型 描述
FeishuError

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

获取文档纯文本内容 参见 feishu.docx.documents.DocxNamespace.list_blocks。

示例：

Python Console Session
1
2
>>> await client.docx.raw_content("doxcabc")
'Hello world\n'
源代码位于： feishu/docx/documents.py
Python
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
async def raw_content(self, document_id: str, *, lang: int | None = None) -> str:
    r"""
    获取文档纯文本内容。

    返回文档去除格式后的纯文本，便于做检索、摘要等文本处理。`lang` 用于控制
    文档中 @ 提及（如人员、文档）等内容的展示语言。

    Args:
        document_id: 文档的唯一标识。
        lang: 内容语言，`0` 默认语言、`1` 中文、`2` 英文；为空时使用接口默认值。

    Returns:
        文档的纯文本内容字符串（取自响应数据的 `content` 字段）。

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

    飞书文档:
        [获取文档纯文本内容](https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/raw_content)
        参见 [feishu.docx.documents.DocxNamespace.list_blocks][]。

    Examples:
        >>> await client.docx.raw_content("doxcabc")  # doctest:+SKIP
        'Hello world\n'
    """
    params = {"lang": lang}
    envelope = await self._client.request(
        "GET", f"docx/v1/documents/{quote_segment(document_id)}/raw_content", params=params
    )
    return _data(envelope)["content"]