Google 文档文档的结构

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

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

顶级元素

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

documents 的顶级元素 资源包括其 TabSuggestionsViewMode, 以及其他属性:

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

标签页

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

  • TabProperties: 包含标签页的属性,例如 ID、标题和索引。
  • childTabs:公开标签页的子标签页(直接嵌套的标签页) 下方)。
  • DocumentTab: 表示标签页的文本内容。
。 <ph type="x-smartling-placeholder">
</ph> 文档标签页的结构。
图 1.文档标签页的结构。

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

如需操控 Body 内容之外的全局文档标签页功能, 通常最好使用一个或多个文档模板,您可以将这些模板 以编程方式生成新文档的基础。如需了解详情,请参阅 将文本合并到文档中

正文内容

Body 通常包含文档标签页中的完整内容。大部分 能或可能希望以编程方式使用的项是 Body 内容:

正文内容的结构。
图 2. 正文内容的结构。

结构元素

StructuralElement 描述的是让文档的结构设计的内容。Body内容 一系列 StructuralElement 对象。内容元素 StructuralElement 对象,如下图所示:

结构元素。
图 3. 结构元素。

结构元素及其内容对象包含所有视觉组件 文档内容。这包括文本、内嵌图片和格式。

段落结构

Paragraph 是 表示段落的 StructuralElement。它涵盖一系列内容 以换行符结束。它由以下对象组成:

  • ParagraphElement: 描述段落中的内容。
  • ParagraphStyle: 用于明确设置段落样式属性的可选元素。
  • Bullet:如果段落 是列表的一部分,它是提供项目符号的可选元素 规范

ParagraphElement 的运作方式类似于 StructuralElement。一组 内容元素类型(例如 ColumnBreakEquation) 对其 拥有 ParagraphElement,如下图所示:

段落元素的结构。
图 4. 段落元素的结构。

有关完整文档结构的示例,请参阅文档 示例(采用 JSON 格式)。在输出中,您可以 可以看到许多关键的结构和内容元素,以及如何使用起始代码 和结束索引,如下一部分所述。

文本生成

TextRunParagraphElement 代表具有相同文本样式的连续文本字符串。答 段落可包含多个文本段,但文本段可跨段落 边界。系统会在一个换行符后拆分内容以形成单独的文本 。例如,假设某个小型文档如下所示:

包含段落和项目符号列表的小文档。
图 5. 小型文档。

下图展示了如何直观呈现段落序列 ,每个类型都有自己的 TextRun 和可选的 Bullet 设置。

文本运行的结构。
图 6. 文本运行的结构。

AutoText

AutoTextParagraphElement,表示文本中动态替换的位置 以及可随时间变化的内容在 Google 文档中,这用于 页码。

起始索引和结束索引

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

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

索引以 UTF-16 代码单元衡量。这意味着代理对使用 两个索引。例如,“GRINNING FACE”表情符号 😄? 表示为 \uD83D\uDE00 并使用两个索引。

对于文档正文内的元素,索引表示相对于 正文内容的开头,即“根”元素。

“个性化”用于构建 元素:SectionBreakTableOfContentsTableParagraph:不具有这些索引,因为它们是 StructuralElement 包含这些字段。同样, ParagraphElement 中包含的类型,例如 TextRunAutoTextPageBreak

访问元素

许多元素都可使用 documents.batchUpdate 方法。例如,使用 InsertTextRequest、 您可以更改任何包含文字的元素的内容。同样,您可以 使用 UpdateTextStyleRequest 可对一个或多个元素中包含的文本范围应用格式。

要读取文档的元素,请使用 documents.get 方法获取 完整文档的 JSON 转储。然后,您可以将生成的 JSON 解析为 求各个元素的值。如需了解详情,请参阅输出 JSON 格式的文档内容

解析内容对各种用例都大有裨益。考虑: 例如,一个文档编目应用列出了它找到的文档。此应用 可以提取文档标题、修订版本 ID 和起始页码, 如下图所示:

文档目录的结构。
图 7. 文档目录的结构。

由于没有明确读取这些设置的方法,因此您的应用需要 来获取整个文档,然后解析 JSON 以提取这些值。

媒体资源继承

StructuralElement 可以从其父对象继承属性。一个 对象的属性,包括其定义的属性和继承的属性, 决定着最终的视觉外观。

文本字符格式决定了文本在文档中如何呈现,例如 粗体、斜体和下划线。您应用的格式会替换默认格式 从基础段落的 TextStyle。反之, 您未设置格式的字符会继续从 段落样式。

段落格式设置决定了文本块在文档中呈现的方式, 例如对齐、边框和缩进您应用的格式 会替换从底层 ParagraphStyle 继承的默认格式。 反之,您未设置的任何格式设置功能都会继续沿用 段落样式