本文由 @张驰 翻译，更新时间：2020-02-16

https://developers.google.com/docs/api/concepts/structure

谷歌文档的结构

本指南解释了 Google Docs 文档的内部结构：组成文档的元素以及这些元素之间的关系。

顶级元素

文档的顶级元素包括正文和文档的许多其他属性作为一个整体：

document: {body: ... , // 文档正文内容documentStyle: ... , //文档样式lists: ... , //列表documentId: ... , //文档IDnamedStyles: ... , //自定义样式revisionId: ... , //修订版本IDtitle: ... //标题
}

若要使用正文内容以外的全局文档特性，使用一个或多个文档模板几乎总是最好的，可以作为生成新文档的编码基础。

文档正文内容 Body Content

你可以或可能希望以编程方式使用的大多数东西都是正文内容中的元素：

 

结构元素 Structural elements

正文内容本质上只是一系列结构元素对象。每个 StructuralElement 对象都通过其内容元素进行个性化设置，如下图所示：

结构元素及其内容对象包含文档的所有文本，嵌入式图像等。

页眉，页脚和脚注类型的内容元素类似地包含一系列结构元素。

段落包含一种称为 ParagraphElement 的特殊元素类型，其工作原理类似于 StructuralElement：通过其自己的一组内容元素类型进行个性化设置，如下图所示：

有关完整文档结构的示例，请参见样本文档 dump(结果文件或者转储)。 在该 dump 中，您可以看到许多关键的结构和内容元素，以及下一节所述的开始和结束索引的使用。

开始和结束索引 Start and end index

正文内容中的大多数元素都具有 startIndex 和 endIndex 属性。这些值表示元素的起点和终点相对于「闭合段」(enclosing segment)起点的偏移量。

段是包含结构或内容元素的正文，页眉，页脚或脚注。 段中元素的索引相对于该段的开始。

索引以UTF-16代码单位进行度量。 这意味着 Surrogate Pairs 消耗两个索引。 例如，“ GRINNING FACE” 😄,表情符号将表示为“ \ uD83D \ uDE00”，并消耗两个索引。

Surrogate Pair是UTF-16中用于扩展字符而使用的编码方式，是一种采用四个字节(两个UTF-16编码)来表示一个字符。

对于文档正文中的元素，这些索引表示距正文内容开头（即“root”元素）的偏移量。

未包含在内容中的元素不具有以下索引属性：它们在范围内是全局的，并且不具有位置概念。

结构元素的“个性化”类型（Paragraph, Table, TableOfContents, 和 SectionBreak）不具有这些索引，因为包围他们的 StructuralElement 具有这些字段。 对于 ParagraphElement 中包含的个性化类型也是如此。

段落结构 Paragraph structure

一个段落由以下元素组成：

• elements - 包含一个或多个 textRun 实例的序列
• paragraphStyle - 段落样式，一个可选元素，为该段落显式设置样式属性。
• bullet - 如果该段落是列表的一部分，则提供项目符号规范的可选元素。

文本行 Text runs

文本行表示所有具有相同文本样式的连续文本字符串。 一个段落可以包含多个文本行； 文字行不能跨越段落边界。 例如，考虑一个如下所示的小文档：

下图显示了如何可视化上述文档中的段落序列，每个段落都有自己的文本运行和可选的项目符号设置。

 

访问元素 Accessing elements

使用 BatchUpdate 方法可以修改许多元素。 例如，使用 InsertTextRequest 请求类型，可以修改任何包含文本的元素的内容。 同样，您可以使用 UpdateTextStyleRequest 将格式应用于一个或多个元素中包含的一系列文本。

要读取文档的元素，请使用 get 方法获取完整文档的 JSON dump。 （要查看执行此操作的简单方法，请参阅将输出文档作为JSON示例。）然后，您可以通过解析的 JSON 结果来查找各个元素的值。

解析内容对于各种用例都是有用的。 例如，一个列出自己找到的文档的文档分类应用程序。 像这样的应用程序可能希望提取文档的标题，修订ID和起始页码，如下图所示：

因为没有显式读取这些设置的方法，所以应用程序需要获取整个文档，然后解析 JSON 以提取这些值。