本指南說明 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 以擷取這些值。