為了有效使用 Google Docs API,您必須瞭解 Google 文件的架構和組成元素 以及文件之間的關係本頁面提供 詳述這些主題:
- 文件元素的概念模型
- Docs API 如何代表這些元素
- 元素的樣式屬性
頂層元素
Google 文件最外層的容器元素是「文件」,這就是 這個單元可儲存在 Google 雲端硬碟中、與其他使用者共用,而且還能更新 包含文字和圖片
documents
的頂層元素
包括其 Tab
SuggestionsViewMode
,
和其他屬性:
document: { title: ... , revisionId: ... , documentId: ... , suggestionsViewMode: ... , tabs: ... }
分頁
單一文件可包含多個分頁,
使用不同的文字內容文件的 tabs
屬性是
Tab
物件的序列。Tab
是由以下欄位組成:
TabProperties
: 包含分頁的屬性,例如 ID、標題和索引。childTabs
:顯示分頁的子分頁 (直接巢狀的分頁) 。DocumentTab
: 代表分頁的文字內容。
後續章節將概略介紹文件分頁階層;這個 Tab JSON 表示法 提供了更詳細的資訊請參閱「使用分頁」一文 進一步瞭解分頁功能
如要操控 Body
內容以外的全域文件分頁功能,
建議您使用一或多個文件範本,這種範本在
以程式輔助的方式生成新文件若需更多資訊,請參閲
將文字合併到文件中。
身體內容
Body
通常包含文件分頁的完整內容。大部分
使用程式輔助功能
Body
內容:
結構元素
StructuralElement
說明為文件提供架構的內容。Body
內容是
StructuralElement
物件的序列。內容元素可用來自訂
StructuralElement
物件,如下圖所示:
結構元素及其內容物件包含所有視覺元件 文件內容包括文字、內嵌圖片和格式設定。
段落結構
Paragraph
是一種
StructuralElement
表示段落。這類內容有多種
以換行字元終止其由以下物件組成:
ParagraphElement
: 說明段落中的內容。ParagraphStyle
: 選擇性元素,以便明確設定段落的樣式屬性。Bullet
:如果段落內容 是清單的一部分,選用元素會提供項目符號 規格。
ParagraphElement
的運作方式與 StructuralElement
類似。一組
內容元素類型 (例如
ColumnBreak
和
Equation
) 的個人化設定
擁有 ParagraphElement
,如下圖所示:
如需完整的文件結構範例,請參閱「 範例。您可以在輸出結果中 其中有許多重要的結構和內容元素,以及運用 以及結束索引,如下一節所述。
文字執行作業
TextRun
是一種
ParagraphElement
代表文字樣式相同的連續文字字串。A 罩杯
paragraph 可以包含多個文字執行,但文字絕不會跨段執行
界定範圍內容會在換行字元之後分隔,形成不同的文字
或任何可執行 Knative 的環境中例如,假設有一份小型文件,如下所示:
![含有段落和項目符號清單的小型文件。](https://developers-dot-devsite-v2-prod.appspot.com/static/docs/api/images/simpledoc.png?authuser=5&hl=zh-tw)
下圖顯示如何以視覺化方式呈現段落序列
各有專屬的 TextRun
和選用 Bullet
可以管理叢集設定,像是節點
資源調度、安全性和其他預先設定項目
AutoText
AutoText
是
ParagraphElement
代表文字中的一個位置
這類內容可能隨時間改變在 Google 文件中,這用於
頁碼。
起始與結束索引
每次更新文件分頁的內容時,系統每次更新都會 可以標記某個位置 或文章中的某個位置這些位置 範圍是使用索引指定,索引是代表 包含文件片段。區隔是指內文、頁首、頁尾或 包含結構或內容元素的註腳。元素索引 與區隔的開頭相關
主體內容中的大多數元素都具有以零為基礎的 startIndex
和
endIndex
屬性。這些元素會指出元素
相對於結束元素的開頭。如要進一步瞭解
如要瞭解如何訂購批次 Docs API 呼叫,請參閱 Batch
更新。
索引是以 UTF-16 代碼單位計算,也就是說,代理組合會耗用
兩個索引例如「GRINNING FACE」表情符號 CANNOT TRANSLATE
\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
沿用的預設格式。
相反地,任何未設定的格式設定功能都會沿用自
建立段落樣式