使用标签页

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

什么是标签页?

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

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

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

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

有了额外的标签页结构层次结构后,这些字段将不再 从语义上表示文档中所有标签页的文本内容。通过 现在,基于文本的内容在另一个层中表示。标签属性和 Google 文档中的内容 document.tabsTab 对象,每个对象 包含上述所有文本内容字段。后面的部分将详细介绍 简要概述;该 标签页 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 设置为 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 资源中的 link.bookmarkIdlink.headingId 字段无法再表示文档中特定标签页中的书签或标题。

开发者应更新其代码,以使用 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();
}