本指南介绍了 Google 文档文档的内部结构:文档的组成元素以及各个元素之间的关系。
顶级元素
文档的顶级元素包括文档的正文以及整个文档的几个其他属性:
document: { body: ... , documentStyle: ... , lists: ... , documentId: ... , namedStyles: ... , revisionId: ... , title: ... }
如需操控正文内容之外的全局文档功能,使用一个或多个文档模板往往是更好的做法,您可以将这些模板用作以程序化方式生成新文档的基础。
正文内容
您可以或可能希望以编程方式使用的大多数项都是正文内容中的元素:
结构元素
正文内容只是一系列 StructuralElement
对象。内容元素对每个 StructuralElement
对象进行了个性化设置,如下图所示:
结构元素及其内容对象包含文档的所有文本、内嵌图片等。
段落包含一种称为 ParagraphElement
的特殊类型的元素,该元素的工作方式类似于 StructuralElement
。一组内容元素类型可对自己的 ParagraphElement
进行个性化设置,如下图所示:
如需查看完整文档结构的示例,请参阅 JSON 格式的文档的示例转储。 在输出中,您可以看到许多关键的结构和内容元素,以及起始索引和结束索引的使用,如下一部分所述。
起始索引和结束索引
正文内容中的大多数元素都具有 startIndex
和 endIndex
属性。这些值表示元素起始和结束位置相对于其外围片段起始位置的偏移量。
索引是以 UTF-16 代码单元来衡量。这意味着代理对使用 2 个索引。例如,“GRINNING FACE”表情符号 😄? 将表示为“\uD83D\uDE00”,并且会使用 2 个索引。
对于文档正文中的元素,索引表示相对于正文内容(即“根”元素)开头部分的偏移量。
结构元素的“个性化”类型(SectionBreak
、TableOfContents
、Table
和 Paragraph
)没有这些索引,因为它们的外围 StructuralElement
包含这些字段。对于 ParagraphElement
中包含的个性化类型,也是如此。
段落结构
段落由以下部分组成:
elements
- 包含一个或多个textRun
实例的序列。paragraphStyle
- 可选元素,用于为段落明确设置样式属性。bullet
- 可选元素,如果段落是列表的一部分,则提供项目符号规范。
文本生成
textRun
表示具有相同文本样式的连续文本字符串。一个段落可以包含多个文本段,但文本段不能跨段落边界。以下面所示的小型文档为例:
下图显示了如何直观呈现上述文档中的段落序列,每个段落都有自己的文本行和可选的项目符号设置。
访问元素
您可以使用 BatchUpdate
方法修改许多元素。例如,使用 InsertTextRequest
请求类型,您可以修改任何包含文本的元素的内容。同样,您可以使用 UpdateTextStyleRequest
对一个或多个元素中包含的一系列文本应用格式。
如需读取文档的元素,请使用 get
方法获取完整文档的 JSON 转储。(如需了解具体操作方法,请参阅以 JSON 格式输出文档内容示例。)然后,您可以解析生成的 JSON 以查找各个元素的值。
解析内容对于各种用例都非常有用。例如,假设有一个为应用编制目录的文档,它列出了它找到的文档。此应用可能需要提取文档的标题、修订版本 ID 和起始页码,如下图所示:
由于没有可明确读取这些设置的方法,因此您的应用需要获取整个文档,然后解析 JSON 以提取这些值。