使用分頁

您可以透過 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 設為 truedocuments.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將成為 系統會將案件套用至文件的第一個分頁 ReplaceAllTextRequestDeleteNamedRangeRequest, 和 ReplaceNamedRangeContentRequest 是三項特殊要求,會預設套用至所有分頁。

詳情請參閱 Request 秒 說明文件。

使用者可以在文件中建立分頁、書籤和標題的內部連結。 導入分頁功能之後,link.bookmarkId 和 有 link.headingId 欄位在 Link 資源已無法再 代表文件中特定分頁的書籤或標題。

開發人員應更新程式碼,改用 link.bookmark和 讀取和寫入作業中的 link.heading。會用來顯示內部連結 BookmarkLinkHeadingLink 物件,每個 內含書籤或標題的 ID 和所在分頁的 ID 。此外,link.tabId 也會提供分頁內部連結。

documents.get的連結內容 回應也可能因 includeTabsContent 參數而異:

  • 如果將 includeTabsContent 設為 true,則所有內部連結都會公開 做為 link.bookmarklink.heading。舊版欄位將不再使用。
  • 如未提供 includeTabsContent,則在包含 單一分頁,連至該單一分頁內的書籤或標題的任何內部連結 繼續顯示為 link.bookmarkIdlink.headingId。在文件中 含有多個分頁,內部連結將顯示為 link.bookmarklink.heading

document.batchUpdate, 如果使用其中一個舊版欄位建立內部連結,書籤或 標題會視為來自 Request。如果沒有分頁 系統會將其視為來自文件的第一個分頁。

連結 JSON 表示法可提供 更多詳細資訊

分頁的常見使用模式

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

朗讀文件中所有分頁的分頁內容

先前執行過的程式碼在分頁功能之前完成遷移,現在仍能支援 將 includeTabsContent 參數設為 true,然後 讀取及呼叫 getter 方法 TabDocumentTab 而非 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();
}