Google 文件架構

本指南說明 Google 文件的內部結構,也就是構成文件的元素及其之間的關係。

頂層元素

文件的頂層元素包含文件的主體和其他數個屬性:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

如要在主體內容以外的位置操控全域文件功能,最好使用一或多個文件範本,以做為程式產生新文件的基礎。

內文

您能夠以程式輔助方式使用的大部分項目都是內文內容中的元素:

內文圖片。

結構元素

主體內容只是一系列的 StructuralElement 物件。內容元素會將每個 StructuralElement 物件個人化,如下圖所示:

結構元素的圖表。

結構元素及其內容物件包含文件的所有文字、內嵌圖片等。

段落包含一種特殊類型的元素,稱為 ParagraphElement,運作方式與 StructuralElement 類似。一組內容元素類型會個人化自己的 ParagraphElement,如下圖所示:

段落元素圖表。

如需完整文件結構的範例,請參閱 JSON 格式的文件範例傾印。輸出內容中會顯示許多重要結構和內容元素,以及使用起始和結束索引的方式,如下一節所述。

起始索引和結尾索引

主體內容中的大部分元素都具備 startIndexendIndex 屬性。這些表示元素起點和終點之間的偏移值 (相對於所屬片段的起點)。

索引的測量單位為 UTF-16 代碼單位,這表示代理組合會使用 2 個索引。舉例來說,「GRINNING FACE」表情符號 🎉? 將表示為「\uD83D\uDE00」,並消耗 2 個索引。

針對文件內文中的元素,索引代表與主體內容開頭的位移,也就是「根」元素。

結構元素的「個人化」類型 (SectionBreakTableOfContentsTableParagraph) 不會有這些索引,因為其包含 StructuralElement 這些欄位。這也適用於 ParagraphElement 中包含的個人化類型。

段落結構

段落由下列項目組成:

  • elements:包含一或多個 textRun 執行個體的序列。
  • paragraphStyle:可明確設定段落樣式屬性的選用元素。
  • bullet:如果段落位於清單,則為選用元素,提供項目符號規格。

文字執行作業

textRun 代表所有文字樣式都相同的連續文字字串。一個段落可以包含多段文字執行,但文字執行不能跨越段落邊界。例如,有一個像這樣的簡易文件:

下圖說明如何以視覺化方式呈現上述文件中段落的序列,且每個段落都有專屬的文字執行和選用的項目符號設定。

文字執行圖表。

存取元素

許多元素都可以使用 BatchUpdate 方法修改。例如,使用 InsertTextRequest 要求類型,即可修改任何包含文字的元素內容。同樣地,您可以使用 UpdateTextStyleRequest 將格式套用至包含在一或多個元素中的一系列文字。

如要讀取文件的元素,請使用 get 方法取得完整文件的 JSON 傾印。(如需操作說明,請參閱「將輸出文件內容做為 JSON 輸出」範例)。接著,您可以剖析產生的 JSON,以找出個別元素的值。

在許多用途上,剖析內容可能會很有幫助。例如,將找到的應用程式列出文件編列目錄。這個應用程式可能會想要擷取文件的標題、修訂版本 ID 和文件的起始頁碼,如下圖所示:

文件目錄應用程式圖表。

由於沒有可明確讀取這些設定的方法,因此應用程式需要取得整份文件,然後剖析 JSON 以擷取這些值。