此页面由 Cloud Translation API 翻译。

使用标签页

通过 Google 文档 API，您可以从文档中的任意标签访问内容。

什么是标签页？

Google 文档具有称为标签页的组织层。 Google 文档允许用户在单个这与目前 Google 表格中的标签页类似每个标签页都有自己的标题和 ID（附加在网址中）。标签页还可以包含子标签页，即嵌套在另一个标签页下的标签页。

目前，我们提供对子标签页的 API 支持，但很快就会提供界面支持。您现在可以在代码中处理子标签页，以便在界面支持启动时您就不必进一步更新代码了。

文档内容在文档资源中的表示方式结构变更

过去，文档没有制表符的概念，因此 Document 直接包含的资源所有文本内容：

有了额外的标签页结构层次结构后，这些字段将不再从语义上表示文档中所有标签页的文本内容。通过现在，基于文本的内容在另一个层中表示。标签属性和 Google 文档中的内容 document.tabs： Tab 对象，每个对象包含上述所有文本内容字段。后面的部分将详细介绍简要概述；该标签页 JSON 表示法也会提供更详细的信息

“访问”标签页属性

通过以下方式访问标签页属性： tab.tabProperties、其中包含标签页 ID、标题和位置等信息。

访问标签页中的文本内容

标签页中的实际文档内容会显示为 tab.documentTab。以下所有权限：可以使用 tab.documentTab 访问上述文本内容字段。例如，您不应使用 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 资源中的 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。如果没有任何标签页将被视为来自文档中的第一个标签页。

通过链接 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();
}