为了有效地使用 Google 文档 API,您必须了解 Google 文档文档的架构和组成文档的元素,以及它们之间的关系。本页面详细介绍了这些主题:
- 文档元素的概念模型
- Google 文档 API 如何表示这些元素
- 元素的样式设置属性
顶级元素
Google 文档最外层的容器元素是文档。这个单元可以保存在 Google 云端硬盘中,与其他用户共享,并更新为文本和图片。
documents
资源的顶级元素包括 Body
、Header
、Footer
以及多个其他属性:
document: { body: ... , documentStyle: ... , lists: ... , documentId: ... , namedStyles: ... , revisionId: ... , title: ... }
如需操纵 Body
内容之外的全局文档功能,最好使用一个或多个文档模板,这些模板可用作以编程方式生成新文档的基础。如需了解详情,请参阅将文本合并到文档中。
正文内容
Body
通常包含完整的文档内容。您可以或可能希望以编程方式使用的大多数项都是 Body
内容中的元素:
结构元素
StructuralElement
描述提供文档结构的内容。Body
内容是一系列 StructuralElement
对象。内容元素会对每个 StructuralElement
对象进行个性化设置,如下图所示:
结构元素及其内容对象包含文档中的所有视觉组件。这包括文本、内嵌图片和格式。
段落结构
Paragraph
是表示段落的 StructuralElement
。它包含以换行符结尾的一系列内容。它由以下对象组成:
ParagraphElement
:描述段落中的内容。ParagraphStyle
:可选元素,用于明确设置段落的样式属性。Bullet
:如果段落是列表的一部分,则为提供项目符号规范的可选元素。
ParagraphElement
的运作方式类似于 StructuralElement
。一组内容元素类型(例如 ColumnBreak
和 Equation
)可对其 ParagraphElement
进行个性化设置,如下图所示:
如需查看完整文档结构的示例,请参阅 JSON 格式的文档示例。在输出中,您可以看到许多关键的结构和内容元素,以及起始索引和结束索引的使用,如以下部分所述。
文本运行
TextRun
是一个 ParagraphElement
,表示具有相同文本样式的连续文本字符串。一个段落可以包含多个文本段,但文本段不会跨越段落边界。内容会在换行符之后进行拆分,以形成单独的文本运行区。例如,假设一个小文档,如下所示:
下图展示了如何直观呈现上述文档中的段落序列,其中每个段落都有自己的 TextRun
和可选的 Bullet
设置。
AutoText
AutoText
是一个 ParagraphElement
,表示文本中的一个点,会动态替换为随时间变化的内容。在 Google 文档中,此键用于页码。
起始索引和结束索引
当您更新文档的内容时,每次更新都是在文档中的一个位置或某个范围内进行的。这些位置和范围使用索引指定,索引表示包含的文档段中的偏移量。段是包含结构或内容元素的正文、页眉、页脚或脚注。线段中元素的索引是相对于该线段开头而言的。
正文内容中的大多数元素都具有从零开始的 startIndex
和 endIndex
属性。这些坐标表示元素起始和结束位置相对于其封闭线段起点的偏移量。如需详细了解如何对 Google 文档 API 的批量调用进行排序,请参阅批量更新。
索引以 UTF-16 代码单元为单位进行衡量。这意味着代理对会使用两个索引。例如,“GRINNING FACE”表情符号 😄? 表示为 \uD83D\uDE00
,它使用两个索引。
对于文档正文中的元素,索引表示相对于正文内容开头(即“根”元素)的偏移量。
结构元素的“个性化”类型(SectionBreak
、TableOfContents
、Table
和 Paragraph
)没有这些索引,因为它们的封闭 StructuralElement
包含这些字段。ParagraphElement
中包含的个性化类型也是如此,例如 TextRun
、AutoText
和 PageBreak
。
访问元素
许多元素都可以使用 documents.batchUpdate
方法修改。例如,您可以使用 InsertTextRequest
更改任何包含文本的元素的内容。同样,您可以使用 UpdateTextStyleRequest
将格式应用于一个或多个元素中包含的一系列文本。
如需读取文档的元素,请使用 documents.get
方法获取完整文档的 JSON 转储。然后,您可以解析生成的 JSON 以查找各个元素的值。如需了解详情,请参阅以 JSON 格式输出文档内容。
解析内容对各种用例都有益。例如,假设某个文档对应用所找到的文档进行了编目。此应用可以提取文档的标题、修订版本 ID 和起始页码,如下图所示:
由于没有可明确读取这些设置的方法,因此您的应用需要获取整个文档,然后解析 JSON 以提取这些值。
继承自媒体资源的权限
StructuralElement
可以从其父对象继承属性。对象的属性(包括其定义的属性和其继承的属性)决定了其最终的视觉外观。
文本字符格式设置决定了文档中文本的呈现方式,例如粗体、斜体和下划线。您应用的格式会替换从基础段落的 TextStyle
继承的默认格式。相反,您未设置格式的所有字符都会继续沿用段落样式。
段落格式设置决定了文档中的文本块的呈现方式,例如对齐、边框和缩进。您应用的格式会替换从底层 ParagraphStyle
继承的默认格式。相反,您未设置的任何格式设置功能会继续沿用段落样式。