这篇文档将会介绍飞书文档的数据结构，包括组成文档的不同元素以及元素之间的关系。

Document

文档的一级结构由以下几部分组成：

document: {
    body: ...,
    title: ...
}

Body

Body 描述了所有的正文内容，文档的 body 由各种 Block 组成。

Block

每个 Block 都是一组结构化元素。从用户的视角来看，每个 Block 即是单独的一行内容。例如文档中的一段文字、一张图片，都分别是一个 Block。

{
    "paragraph": {object(Paragraph)},
    "horizontalLine": {object(HorizontalLine)},
    "embeddedPage": {object(EmbeddedPage)},
    "chatGroup": {object(ChatGroup)},
    "table": {object(Table)},
    "sheet": {object(Sheet)},
    "bitable": {object(Bitable)}
}

Location

我们通过 zoneId、startIndex 和 endIndex 来标记 body 中每个 block 的位置。其中，zoneId 标记文档的不同区域，对于所有文档，正文部分的 zoneId 都是“0”，表格的单元格则是一个不规则的字符串。startIndex 和 endIndex 使用 utf-16 编码格式来标记一个 block 的起止位置偏移量。每个 Block 都有对应的 index 对其绝对位置进行标记。由于飞书文档是协同文档，在获取到一个文档，并提交编辑请求的过程中，这个文档可能被其他的用户修改，导致偏移量发生变化。如果仍然按照读取时的状态进行修改，则会影响正文的准确性。为了避免上述问题造成提交失败或者结果不正确，飞书文档会根据请求中上传的 revisionId 自动计算上次请求和最新的线上内容的偏移，不需要开发者做额外的工作。

Paragraph

Paragraph 是文档正文的段落，由 ParagraphElement（段落元素）、Location、ParagraphStyle（段落样式）组成。Paragraph 的结构可以通过下面的数据结构描述：

{
    "elements":  [{object (ParagraphElement)}],
    "loc": {object(Location)}
    "style": object (ParagraphStyle),
}

这是一段示例文本，用来描述一段加粗的文本，这是一种常见的组合样式。
这是一组无序列表
这组无序列表包含 3 个节点
每个无序列表节点都是一个独立的段落
通过 API，也可以插入这样的内容。

如果用图形化的方式来表示上面这些文字的格式，应当如下图所示：

本文大致介绍了文档的数据结构，接下来，你可以阅读文档数据结构参考来了解更多。

文档数据结构概述

Document#

Body#

Block#

Location#

Paragraph#

Document

Body

Block

Location

Paragraph