此页面由 Cloud Translation API 翻译。

Google 文档文档的结构

为了有效地使用 Google 文档 API，您必须了解 Google 文档文档架构以及组成以及它们之间的关系。本页介绍了以下主题的详细说明：

文档元素的概念模型
Google 文档 API 如何表示这些元素
元素的样式属性

。

顶级元素

Google 文档中最外层的容器元素是“文档”。这是可以保存在 Google 云端硬盘中、与其他用户共享以及更新的单位。包含文字和图片

documents 的顶级元素资源包括其 Tab、 SuggestionsViewMode, 以及其他属性：

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

标签页

一个文档可以包含多个制表符，具有不同的文本级内容。文档的 tabs 属性是 Tab 对象的序列。Tab 由以下字段组成：

TabProperties：包含标签页的属性，例如 ID、标题和索引。
childTabs：公开标签页的子标签页（直接嵌套的标签页）下方）。
DocumentTab：表示标签页的文本内容。

。 <ph type="x-smartling-placeholder">

后续部分将简要介绍文档标签页的层次结构：该标签页 JSON 表示法可提供更详细的信息请参阅使用标签页以便详细了解标签页功能

如需操控 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 文档中，这用于页码。

起始索引和结束索引

当您更新文档标签的内容时，每次更新都会文档中的某个位置或某个范围的位置。这些位置和范围使用 indexes 指定，indexes 表示包含文档 segment。细分受众群是网页正文、页眉、页脚或包含结构或内容元素的脚注。元素的索引都相对于该片段的开头。

正文内容中的大多数元素都具有从零开始的 startIndex，并且 endIndex 属性。它们表示元素起始位置的偏移量结束位置。更多信息有关如何对 Google 文档批量调用进行排序，请参阅批量处理更新。

索引以 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 继承的默认格式。反之，您未设置的任何格式设置功能都会继续沿用段落样式