为了有效地使用 Google 文档 API,您必须了解 Google 文档文档架构以及组成 以及它们之间的关系。本页介绍了 以下主题的详细说明:
- 文档元素的概念模型
- Google 文档 API 如何表示这些元素
- 元素的样式属性
顶级元素
Google 文档中最外层的容器元素是“文档”。这是 可以保存在 Google 云端硬盘中、与其他用户共享以及更新的单位。 包含文字和图片
documents
的顶级元素
资源包括其 Tab
、
SuggestionsViewMode
,
以及其他属性:
document: { title: ... , revisionId: ... , documentId: ... , suggestionsViewMode: ... , tabs: ... }
标签页
一个文档可以包含多个制表符,
具有不同的文本级内容。文档的 tabs
属性是
Tab
对象的序列。Tab
由以下字段组成:
TabProperties
: 包含标签页的属性,例如 ID、标题和索引。childTabs
:公开标签页的子标签页(直接嵌套的标签页) 下方)。DocumentTab
: 表示标签页的文本内容。
后续部分将简要介绍文档标签页的层次结构:该 标签页 JSON 表示法 可提供更详细的信息请参阅使用标签页 以便详细了解标签页功能
如需操控 Body
内容之外的全局文档标签页功能,
通常最好使用一个或多个文档模板,您可以将这些模板
以编程方式生成新文档的基础。如需了解详情,请参阅
将文本合并到文档中。
正文内容
Body
通常包含文档标签页中的完整内容。大部分
能或可能希望以编程方式使用的项是
Body
内容:
结构元素
StructuralElement
描述的是使文档结构的结构。Body
内容
一系列 StructuralElement
对象。内容元素
StructuralElement
对象,如下图所示:
结构元素及其内容对象包含所有视觉组件 文档内容。这包括文本、内嵌图片和格式。
段落结构
Paragraph
是
表示段落的 StructuralElement
。它涵盖一系列内容
以换行符结束。它由以下对象组成:
ParagraphElement
: 描述段落中的内容。ParagraphStyle
: 用于明确设置段落样式属性的可选元素。Bullet
:如果段落 是列表的一部分,它是提供项目符号的可选元素 规范
ParagraphElement
的运作方式类似于 StructuralElement
。一组
内容元素类型(例如
ColumnBreak
和
Equation
) 对其
拥有 ParagraphElement
,如下图所示:
有关完整文档结构的示例,请参阅文档 示例(采用 JSON 格式)。在输出中,您可以 可以看到许多关键的结构和内容元素,以及如何使用起始代码 和结束索引,如下一部分所述。
文本生成
TextRun
是
ParagraphElement
代表具有相同文本样式的连续文本字符串。答
段落可包含多个文本段,但文本段可跨段落
边界。系统会在一个换行符后拆分内容以形成单独的文本
。例如,假设某个小型文档如下所示:
![包含段落和项目符号列表的小文档。](https://developers.google.cn/static/docs/api/images/simpledoc.png?authuser=8&hl=zh-cn)
下图展示了如何直观呈现段落序列
,每个类型都有自己的 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
继承的默认格式。
反之,您未设置的任何格式设置功能都会继续沿用
段落样式