本頁面由 Cloud Translation API 翻譯而成。

使用分頁

您可以透過 Google Docs API，從文件的任何分頁存取內容。

什麼是分頁？

Google 文件提供了組織層，稱為「分頁」。 Google 文件可讓使用者在單一單一分頁中建立一或多個分頁文件，類似目前的 Google 試算表分頁功能。每個分頁都有專屬的標題和 ID (附加在網址中)。分頁標籤也可以包含子項分頁，位於其他分頁的巢狀結構下

我們目前已推出子項分頁的 API 支援，但近期也將支援 UI。您可以立即在程式碼中處理子分頁，以便在支援 UI 時啟動因此您不需要進一步更新程式碼

文件內容在文件資源表示方式的結構異動

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

只要使用額外的分頁結構階層，這些欄位就不再需要以語意方式呈現文件中所有分頁的文字內容。文字內容現在會以不同的圖層呈現。分頁屬性和可以透過以下瀏覽器存取 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。存取文件需要遍歷「樹木」下層分頁舉例來說，請考慮包含下列分頁階層的文件：

含有三個頂層分頁的分頁清單 UI，其中幾個分頁有子分頁

為了擷取 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();
}