您可以透過 Google Docs API,從文件的任何分頁存取內容。
什麼是分頁?
Google 文件提供了組織層,稱為「分頁」。 Google 文件可讓使用者在單一單一分頁中建立一或多個分頁 文件,類似目前的 Google 試算表分頁功能。每個分頁都有 。分頁標籤也可以包含子項分頁, 位於其他分頁的巢狀結構下
我們目前已推出子項分頁的 API 支援,但近期也將支援 UI。 您可以立即在程式碼中處理子分頁,以便在支援 UI 時啟動 因此您不需要進一步更新程式碼
文件內容在文件資源表示方式的結構異動
文件過去並沒有分頁的概念,因此
Document
直接包含
請透過下列欄位列出所有文字內容:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
只要使用額外的分頁結構階層,這些欄位就不再需要
以語意方式呈現文件中所有分頁的文字內容。
文字內容現已在另一個圖層中呈現。分頁屬性和
可以透過以下瀏覽器存取 Google 文件中的內容:
document.tabs
,也就是
Tab
物件,
包含所有上述文字內容欄位。後續章節提供
大略簡介這個
分頁 JSON 表示法
也提供更詳細的資訊
存取分頁屬性
透過以下方式存取分頁屬性:
tab.tabProperties
,
其中包括分頁 ID、標題和位置等資訊
存取分頁中的文字內容
分頁中的實際文件內容會顯示為
tab.documentTab
。所有的運算
上述文字內容欄位可使用 tab.documentTab
存取。
舉例來說,您應該使用 document.body
,不要使用 document.body
document.tabs[indexOfTab].documentTab.body
。
分頁階層
子分頁在 API 中會以
已啟用 tab.childTabs
欄位
Tab
。存取
文件需要遍歷「樹木」下層分頁舉例來說,假設
包含下列分頁階層的文件:
為了擷取 Body
方法是前往 Tab 3.1.2
document.tabs[2].childTabs[0].childTabs[1].documentTab.body
。查看範例
下一節的程式碼區塊,提供疊代的程式碼範例
文件的所有分頁
方法異動
隨著分頁推出,每種文件方法都有幾項差異 您可能需要更新程式碼
documents.get
根據預設,系統不會傳回所有分頁內容。開發人員應更新
即可存取所有分頁
documents.get
方法會顯示
includeTabsContent
參數,用來設定是否來自
都會在回應中提供所有分頁
- 如果將
includeTabsContent
設為true
,documents.get
方法會傳回 一項Document
資源 已填入document.tabs
欄位。「document
」上的所有文字欄位直接 (例如document.body
) 會留空。 - 如未提供
includeTabsContent
,則Document
資源 (例如document.body
) 中的文字欄位只會填入第一個分頁的內容。document.tabs
欄位將空白,而且不會傳回其他分頁的內容。
documents.create
documents.create
方法
會傳回 Document
資源
代表建立的空白文件傳回的
Document
資源會填入
文件的文字內容欄位也包含空白文件內容
document.tabs
。
document.batchUpdate
每個 Request
都包含
用於指定要套用更新的分頁。根據預設
會指定
Request
將成為
系統會將案件套用至文件的第一個分頁
ReplaceAllTextRequest
,
DeleteNamedRangeRequest
,
和
ReplaceNamedRangeContentRequest
是三項特殊要求,會預設套用至所有分頁。
詳情請參閱
Request
秒
說明文件。
對內部連結所做的變更
使用者可以在文件中建立分頁、書籤和標題的內部連結。
導入分頁功能之後,link.bookmarkId
和
有 link.headingId
欄位在
Link
資源已無法再
代表文件中特定分頁的書籤或標題。
開發人員應更新程式碼,改用 link.bookmark
和
讀取和寫入作業中的 link.heading
。會用來顯示內部連結
BookmarkLink
和
HeadingLink
物件,每個
內含書籤或標題的 ID 和所在分頁的 ID
。此外,link.tabId
也會提供分頁內部連結。
documents.get
的連結內容
回應也可能因 includeTabsContent
參數而異:
- 如果將
includeTabsContent
設為true
,則所有內部連結都會公開 做為link.bookmark
和link.heading
。將不再使用舊版欄位。 - 如未提供
includeTabsContent
,則在包含 單一分頁,連至該單一分頁內的書籤或標題的任何內部連結 繼續顯示為link.bookmarkId
和link.headingId
。在文件中 含有多個分頁,內部連結將顯示為link.bookmark
和link.heading
。
在document.batchUpdate
,
如果使用其中一個舊版欄位建立內部連結,書籤或
標題會視為來自
Request
。如果沒有分頁
系統會將其視為來自文件的第一個分頁。
連結 JSON 表示法可提供 更多詳細資訊
常見的分頁使用模式
以下程式碼範例說明與分頁互動的各種方式。
朗讀文件中所有分頁的分頁內容
先前執行過的程式碼在分頁功能之前完成遷移,現在仍能支援
將 includeTabsContent
參數設為 true
,然後
讀取及呼叫 getter 方法
Tab
和
DocumentTab
而非
Document
。以下部分
程式碼範例是以
擷取文件中的文字。代表
如何列印文件每個分頁的文字內容。這個分頁
週遊程式碼可用於許多其他不關心用途
分頁的實際結構
Java
/** Prints all text contents from all tabs in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from each tab in the document. for (Tab tab: allTabs) { // Get the DocumentTab from the generic Tab. DocumentTab documentTab = tab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); } } /** * Returns a flat list of all tabs in the document in the order they would * appear in the UI (top-down ordering). Includes all child tabs. */ private List<Tab> getAllTabs(Document doc) { List<Tab> allTabs = new ArrayList<>(); // Iterate over all tabs and recursively add any child tabs to generate a // flat list of Tabs. for (Tab tab: doc.getTabs()) { addCurrentAndChildTabs(tab, allTabs); } return allTabs; } /** * Adds the provided tab to the list of all tabs, and recurses through and * adds all child tabs. */ private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) { allTabs.add(tab); for (Tab tab: tab.getChildTabs()) { addCurrentAndChildTabs(tab, allTabs); } } /** * Recurses through a list of Structural Elements to read a document's text * where text may be in nested elements. * * <p>For a code sample, see * <a href="https://developers.google.com/docs/api/samples/extract-text">Extract * the text from a document</a>. */ private static String readStructuralElements(List<StructuralElement> elements) { ... }
朗讀文件第一個分頁的分頁內容
這與讀取所有分頁的方式類似。
Java
/** Prints all text contents from the first tab in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from the first tab in the document. Tab firstTab = allTabs.get(0); // Get the DocumentTab from the generic Tab. DocumentTab documentTab = firstTab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); }
要求更新第一個分頁
下列部分程式碼範例說明如何指定
Request
。這組代碼
是以
「插入、刪除及移動文字」指南。
Java
/** Inserts text into the first tab of the document. */ static void insertTextInFirstTab(Docs service, String documentId) throws IOException { // Get the first tab's ID. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); Tab firstTab = doc.getTabs().get(0); String tabId = firstTab.getTabProperties().getTabId(); List<Request>requests = new ArrayList<>(); requests.add(new Request().setInsertText( new InsertTextRequest().setText(text).setLocation(new Location() // Set the tab ID. .setTabId(tabId) .setIndex(25)))); BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests); BatchUpdateDocumentResponse response = docsService.documents().batchUpdate(DOCUMENT_ID, body).execute(); }