Trabaja con pestañas

La API de Documentos de Google te permite acceder a contenido desde cualquier pestaña del documento.

¿Qué son las pestañas?

Documentos de Google cuenta con una capa organizativa llamada pestañas. Documentos permite a los usuarios crear una o más pestañas en una misma pestaña similar a como existen pestañas en Hojas de cálculo en la actualidad. Cada pestaña tiene su propio ID y título (anexados en la URL). Una pestaña también puede tener pestañas secundarias, pestañas anidadas dentro de otra pestaña.

Actualmente, la compatibilidad de la API para las pestañas secundarias ya está disponible, pero pronto se admitirá la IU. Actualmente, puedes controlar las pestañas secundarias de tu código para que, cuando se inicie la compatibilidad de la IU no tendrás que realizar más actualizaciones de código.

Cambios estructurales en cómo se representa el contenido del documento en el recurso de documento.

En el pasado, los documentos no tenían el concepto de pestañas, por lo que Document Recurso contenido directamente todo el contenido de texto a través de los siguientes campos:

Con la jerarquía estructural adicional de las pestañas, estos campos ya no representan semánticamente el contenido de texto de todas las pestañas del documento. El el contenido basado en texto ahora se representa en una capa diferente. Propiedades de la pestaña y contenido de Documentos de Google son accesibles con document.tabs, que es una lista de Tab, cada uno de los cuales contiene todos los campos de contenido de texto antes mencionados. En las secciones posteriores una breve descripción general; el Representación JSON de la pestaña también brinda información más detallada.

Acceder a las propiedades de la pestaña

Accede a las propiedades de la pestaña con tab.tabProperties, que incluye información como el ID, el título y la posición de la pestaña.

Cómo acceder al contenido de texto dentro de una pestaña

El contenido real del documento dentro de la pestaña se expone como tab.documentTab Todos Se puede acceder a los campos de contenido de texto antes mencionados utilizando tab.documentTab. Por ejemplo, en lugar de usar document.body, debes usar document.tabs[indexOfTab].documentTab.body

Jerarquía de pestañas

Las pestañas secundarias se representan en la API como Campo tab.childTabs activado Tab Acceder a todas las pestañas de una documento requiere recorrer el “árbol” de pestañas secundarias. Por ejemplo, considera un documento que contiene una jerarquía de pestañas como se muestra a continuación:

IU de lista de pestañas con tres pestañas de nivel superior, algunas de las cuales tienen pestañas secundarias

Para recuperar el Body desde la Tab 3.1.2, accederás document.tabs[2].childTabs[0].childTabs[1].documentTab.body Ver la muestra bloques de código en la sección posterior, que proporciona código de muestra para iterar en todas las pestañas de un documento.

Cambios en los métodos

Con la introducción de las pestañas, cada uno de los métodos del documento tiene algunos cambios que pueden requerir que actualices tu código.

documents.get

De forma predeterminada, no se muestra todo el contenido de las pestañas. Los desarrolladores deben actualizar sus código para acceder a todas las pestañas. El El método documents.get expone un includeTabsContent, que permite configurar si los contenidos se proporcionan todas las pestañas en la respuesta.

  • Si includeTabsContent se configura como true, Se mostrará el método documents.get un recurso Document con el Se propagó al campo document.tabs. Todos los campos de texto directamente en document (p.ej., document.body) quedarán vacías.
  • Si no se proporciona includeTabsContent, los campos de texto del recurso Document (p.ej., document.body) se propagarán solo con el contenido de la primera pestaña. El campo document.tabs estará vacío, y no se mostrará el contenido de otras pestañas.

documents.create

Método documents.create Devuelve un recurso Document. que representa el documento vacío que se creó. El valor devuelto Document El recurso propagará el el contenido del documento vacío en los campos de contenido de texto del documento y, document.tabs

document.batchUpdate

Cada Request incluye una forma de especificar las pestañas a las que se aplicará la actualización. Por defecto, si una pestaña no está especificado, el valor Request hará lo siguiente en la mayoría los casos se aplicarán a la primera pestaña del documento. ReplaceAllTextRequest, DeleteNamedRangeRequest, y ReplaceNamedRangeContentRequest hay tres solicitudes especiales que, en su lugar, se aplicarán a todas las pestañas de forma predeterminada.

Consulta las Requests documentación para obtener información específica.

Los usuarios pueden crear vínculos internos a pestañas, favoritos y encabezados de un documento. Con la introducción de la función de pestañas, link.bookmarkId y Campos link.headingId en el El recurso Link ya no puede representar un marcador o encabezado en una pestaña concreta del documento.

Los desarrolladores deben actualizar su código para usar link.bookmark y link.heading en operaciones de lectura y escritura. Exponen vínculos internos con BookmarkLink y HeadingLink objetos, cada uno que contenga el ID del marcador o encabezado y el ID de la pestaña en la que se encuentra en el que te etiquetaron. Además, link.tabId expone vínculos internos a pestañas.

Vincula el contenido de una documents.get también puede variar según el parámetro includeTabsContent:

  • Si estableces includeTabsContent como true, se mostrarán todos los vínculos internos. como link.bookmark y link.heading. Ya no se usarán los campos heredados.
  • Si no se proporciona includeTabsContent, entonces, en los documentos que contengan un una sola pestaña, vínculos internos a marcadores o encabezados dentro de esa pestaña única siguen exponiéndose como link.bookmarkId y link.headingId. En documentos que contenga varias pestañas, los vínculos internos se mostrarán como link.bookmark y link.heading

En document.batchUpdate, Si se crea un vínculo interno mediante uno de los campos heredados, el marcador o encabezado se considerará del ID de la pestaña especificado en el Request Si no hay ninguna pestaña especificada, se considerará que proviene de la primera pestaña del documento.

El La representación JSON de vínculos proporciona información más detallada.

Patrones de uso comunes para pestañas

En las siguientes muestras de código, se describen varias formas de interactuar con las pestañas.

Lee el contenido de la pestaña de todas las pestañas del documento

El código existente que hizo esto antes de la función de pestañas se puede migrar para admitir pestañas estableciendo el parámetro includeTabsContent en true, y recorre el de la jerarquía del árbol de pestañas y de llamar a los métodos get desde Tab y DocumentTab en lugar de Document. La siguiente consulta parcial de la muestra de código se basa en el fragmento en Extrae el texto de un documento. Muestra cómo imprimir todo el contenido de texto de cada pestaña de un documento. Esta pestaña El código transversal puede adaptarse a muchos otros casos de uso a los que no les interesa la estructura real de las pestañas.

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) {
  ...
}

Leer el contenido de la pestaña de la primera pestaña del documento

Esto es similar a leer todas las pestañas.

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()));
}

Haz una solicitud para actualizar la primera pestaña

La siguiente muestra de código parcial indica cómo orientarse a una pestaña específica en una Request Este código se basa en la muestra del Insertar, borrar y mover texto Guía.

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();
}