使用分頁

您可以使用 Google 文件 API 存取文件中任何分頁的內容。

什麼是分頁？

Google 文件提供稱為「分頁」的組織層。 使用者可在單一文件中建立一或多個分頁，與現今 Google 試算表的分頁功能類似。每個分頁都有自己的標題和 ID (附加在網址中)。分頁也可以有子分頁，也就是巢狀結構的分頁。

文件資源中文件內容的呈現方式發生結構性變化

過去，文件沒有分頁的概念，因此 Document 資源會透過下列欄位直接包含所有文字內容：

由於分頁新增了結構階層，這些欄位不再從語意上代表文件中所有分頁的文字內容。現在文字內容會顯示在不同圖層中。您可以使用 document.tabs 存取 Google 文件的表格屬性和內容，這是 Tab 物件的清單，每個物件都包含上述所有文字內容欄位。後續章節會簡要說明，而 Tab JSON 表示法也會提供更詳細的資訊。

存取分頁屬性

使用 tab.tabProperties 存取分頁屬性，包括分頁的 ID、標題和位置等資訊。

存取分頁中的文字內容

分頁中的實際文件內容會顯示為 tab.documentTab。您可以使用 tab.documentTab 存取上述所有文字內容欄位。舉例來說，請使用 document.tabs[indexOfTab].documentTab.body，而非 document.body。

分頁階層

API 中的子分頁會以 Tab 上的 tab.childTabs 欄位表示。如要存取文件中的所有分頁，必須遍歷子分頁的「樹狀結構」。舉例來說，假設文件包含下列分頁階層：

含有三個頂層分頁的 Tablist UI，其中部分分頁含有子分頁

如要擷取 Body，請存取分頁 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 資源中的 link.bookmarkId 和 link.headingId 欄位不再代表文件中特定分頁的書籤或標題。

開發人員應更新程式碼，在讀取和寫入作業中使用 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 中指定的索引標籤 ID。如果未指定索引標籤，系統會視為來自文件中的第一個索引標籤。

連結 JSON 表示法提供更詳細的資訊。

分頁的常見使用模式

下列程式碼範例說明與分頁互動的各種方式。

從文件中的所有分頁讀取分頁內容

如要將先前執行這項操作的現有程式碼遷移至支援分頁功能，請將 includeTabsContent 參數設為 true，遍歷分頁樹狀結構階層，然後呼叫 Tab 和 DocumentTab 的 getter 方法，而不是 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/workspace/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();
}