Trabaja con pestañas

Google Apps Script para Documentos de Google te permite acceder al contenido de cualquier pestaña del documento.

¿Qué son las pestañas?

Documentos incluye una capa organizativa llamada pestañas. Documentos permite que los usuarios creen una o más pestañas dentro de un solo documento, de forma similar a como existen las pestañas en Hojas de cálculo hoy en día. Cada pestaña tiene su propio título y un ID (que se agrega a la URL). Una pestaña también puede tener pestañas secundarias, que son pestañas que están anidadas debajo de otra pestaña.

Accede a las pestañas

Se puede acceder a las propiedades y el contenido de las pestañas con Document.getTabs, que muestra una lista de Tabs. En las siguientes secciones, se ofrece una breve descripción general de la Tab clase. La documentación de la clase Tab también proporciona información más detallada.

Propiedades de las pestañas

Las propiedades de las pestañas se pueden recuperar con métodos como Tab.getId y Tab.getTitle.

Contenido de las pestañas

El contenido del documento dentro de cada pestaña se puede recuperar con Tab.asDocumentTab. En la sección Cambios en la estructura de la clase Document , se describe cómo se puede usar.

Jerarquía de pestañas

Las pestañas secundarias se exponen en Apps Script a través de Tab.getChildTabs. Para acceder al contenido de todas las pestañas, es necesario recorrer el "árbol" de pestañas secundarias. Por ejemplo, considera un documento que contiene una jerarquía de pestañas de la siguiente manera:

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

Para acceder a Pestaña 3.1.2, haz lo siguiente:

// Print the ID of Tab 3.1.2.
const doc = DocumentApp.getActiveDocument();
const tab = doc.getTabs()[2].getChildTabs()[0].getChildTabs()[1];
console.log(tab.getId());

Consulta los bloques de código de muestra en las secciones posteriores para obtener un código de muestra que itere en todas las pestañas de un documento.

Otras formas de recuperar pestañas

Existen otras dos formas de recuperar pestañas:

Cambios en la estructura de la clase Document

En el pasado, los documentos no tenían un concepto de pestañas, por lo que la clase Document exponía métodos para acceder directamente al contenido de texto del documento y modificarlo. Los siguientes métodos pertenecen a esta categoría:

Con la jerarquía estructural adicional de las pestañas, estos métodos ya no representan semánticamente el contenido de texto de todas las pestañas del documento. El contenido de texto ahora se representará en una capa diferente. Se puede acceder a todos los métodos de texto mencionados anteriormente a través de DocumentTab.

Estos métodos existentes en la clase Document accederán al contenido de la pestaña activa (en secuencias de comandos vinculadas a un documento en particular) o a la primera pestaña (si no hay una activa) o lo modificarán.

Accede al contenido de texto dentro de una pestaña específica

En lugar de usar los métodos de texto de Document, se recomienda usar los métodos que están disponibles en la clase DocumentTab en su lugar (que está disponible a través del Tab.asDocumentTab método). Por ejemplo:

// Print the text from the body of the active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const body = documentTab.getBody();
console.log(body.getText());

Cambios en la selección del usuario

El concepto de la selección del usuario solo es relevante y solo puede ser usado o cambiado por secuencias de comandos vinculadas a un documento.

Métodos de selección de texto

La clase Document proporciona captadores y establecedores para administrar dónde selecciona el usuario en el texto, dentro del documento activo. Estos métodos operan en el contexto de la pestaña activa del usuario que ejecuta la secuencia de comandos.

  • Document.getCursor: Muestra la posición del cursor del usuario en la pestaña activa.
  • Document.getSelection: Muestra el rango de selección del usuario en la pestaña activa.
  • Document.setCursor: Establece la posición del cursor del usuario en el documento activo. Si la posición está en una pestaña inactiva, la pestaña activa del usuario también cambia a la pestaña asociada con esa posición.
  • Document.setSelection: Establece el rango de selección del usuario en el documento activo. Si el rango está en una pestaña inactiva, la pestaña activa del usuario también cambia a la pestaña asociada con ese rango.

Métodos de selección de pestañas y casos de uso

Con la introducción de las pestañas, obtén y establece la pestaña activa del usuario que ejecuta la secuencia de comandos. Usa los siguientes métodos:

La "selección" integral del usuario se compone de una combinación de la pestaña activa junto con la posición actual del cursor o el rango de selección. Los dos patrones para trabajar con una selección activa son modificar explícitamente la pestaña activa del usuario a una pestaña específica o usar la pestaña activa del usuario.

Para cambiar explícitamente la pestaña activa del usuario, usa Document.setActiveTab. Como alternativa, llamar a Document.setCursor o Document.setSelection con una Position o Range desde una pestaña inactiva hace que esa pestaña esté activa recientemente.

Si el comportamiento previsto de la secuencia de comandos es usar la pestaña activa del usuario sin cambiarla, entonces Document.setActiveTab no es necesario. Los métodos Document.getCursor y Document.getSelection operan en la pestaña activa, según la pestaña desde la que el usuario ejecuta la secuencia de comandos.

Un documento no admite varias selecciones de pestañas ni varias posiciones o rangos en diferentes pestañas. Por lo tanto, usar Document.setActiveTab borra la posición anterior del cursor o el rango de selección.

Métodos de posición y rango para una pestaña específica

La pestaña específica da significado a los conceptos de selección de texto de Position y Range. Una posición del cursor o un rango de selección solo son significativos si la secuencia de comandos conoce la pestaña específica en la que se encuentra la posición o el rango.

Esto se logra mediante los métodos DocumentTab.newPosition y DocumentTab.newRange, que construyen una posición o un rango que apunta a la DocumentTab específica desde la que se llama al método. Por el contrario, Document.newPosition y Document.newRange construyen una posición o un rango dentro de la pestaña activa (o la primera pestaña, si la secuencia de comandos no está vinculada).

Consulta los bloques de código de muestra en las secciones posteriores para obtener un código de muestra para trabajar con selecciones.

Patrones de uso comunes para las pestañas

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

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

El código existente que hacía esto antes de la función de pestañas se puede migrar para admitir pestañas recorriendo el árbol de pestañas y llamando a los métodos getter de Tab y DocumentTab en lugar de Document. En el siguiente ejemplo de muestra de código parcial, se muestra cómo imprimir todo el contenido de texto de cada pestaña de un documento. Este código de recorrido de pestañas se puede adaptar a muchos otros casos de uso que no se preocupan por la estructura real de las pestañas.

/** Logs all text contents from all tabs in the active document. */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs. DocumentApp.openById('abc123456') can also
  // be used instead of DocumentApp.getActiveDocument().
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from each tab in the document.
  for (const tab of allTabs) {
    // Get the DocumentTab from the generic Tab object.
    const documentTab = tab.asDocumentTab();
    // Get the body from the given DocumentTab.
    const body = documentTab.getBody();
    // Get the body text and log it to the console.
    console.log(body.getText());
  }
}

/**
 * Returns a flat list of all tabs in the document, in the order
 * they would appear in the UI (i.e. top-down ordering). Includes
 * all child tabs.
 */
function getAllTabs(doc) {
  const allTabs = [];
  // Iterate over all tabs and recursively add any child tabs to
  // generate a flat list of Tabs.
  for (const tab of 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.
 */
function addCurrentAndChildTabs(tab, allTabs) {
  allTabs.push(tab);
  for (const childTab of tab.getChildTabs()) {
    addCurrentAndChildTabs(childTab, allTabs);
  }
}

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

Es similar a leer todas las pestañas.

/** 
 * Logs all text contents from the first tab in the active 
 * document. 
 */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs.
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from the first tab in the document.
  const firstTab = allTabs[0];
  // Get the DocumentTab from the generic Tab object.
  const documentTab = firstTab.asDocumentTab();
  // Get the body from the DocumentTab.
  const body = documentTab.getBody();
  // Get the body text and log it to the console.
  console.log(body.getText());
}

Actualiza el contenido de las pestañas en la primera pestaña

En el siguiente ejemplo de código parcial, se muestra cómo segmentar una pestaña específica cuando se realizan actualizaciones.

/** Inserts text into the first tab of the active document. */
function insertTextInFirstTab() {
  // Get the first tab's body.
  const doc = DocumentApp.getActiveDocument();
  const firstTab = doc.getTabs()[0];
  const firstDocumentTab = firstTab.asDocumentTab();
  const firstTabBody = firstDocumentTab.getBody();

  // Append a paragraph and a page break to the first tab's body
  // section.
  firstTabBody.appendParagraph("A paragraph.");
  firstTabBody.appendPageBreak();
}

Actualiza el contenido de las pestañas en la pestaña activa o seleccionada

En el siguiente ejemplo de muestra de código parcial, se muestra cómo segmentar la pestaña activa cuando se realizan actualizaciones.

/**
 * Inserts text into the active/selected tab of the active
 * document.
 */
function insertTextInActiveTab() {
  // Get the active/selected tab's body.
  const doc = DocumentApp.getActiveDocument();
  const activeTab = doc.getActiveTab();
  const activeDocumentTab = activeTab.asDocumentTab();
  const activeTabBody = activeDocumentTab.getBody();

  // Append a paragraph and a page break to the active tab's body
  // section.
  activeTabBody.appendParagraph("A paragraph.");
  activeTabBody.appendPageBreak();
}

Establece una posición del cursor o un rango de selección en la pestaña activa

En el siguiente ejemplo de muestra de código parcial, se muestra cómo actualizar la posición del cursor o el rango de selección dentro de la pestaña activa del usuario. Esto solo es relevante en secuencias de comandos vinculadas.

/**
 * Changes the user's selection to select all tables within the tab
 * with the provided ID.
 */
function selectAllTables(tabId) {
  const doc = DocumentApp.getActiveDocument();
  const tab = doc.getTab(tabId);
  const documentTab = tab.asDocumentTab();

  // Build a range that encompasses all tables within the specified
  // tab.
  const rangeBuilder = documentTab.newRange();
  const tables = documentTab.getBody().getTables();
  for (let i = 0; i < tables.length; i++) {
    rangeBuilder.addElement(tables[i]);
  }
  // Set the document's selection to the tables within the specified
  // tab. Note that this actually switches the user's active tab as
  // well.
  doc.setSelection(rangeBuilder.build());
}

Establece la pestaña activa o seleccionada

En el siguiente ejemplo de muestra de código parcial, se muestra cómo cambiar la pestaña activa del usuario. Esto solo es relevante en secuencias de comandos vinculadas.

/**
 * Changes the user's selected tab to the tab immediately following
 * the currently selected one. Handles child tabs.
 *
 * 
Only changes the selection if there is a tab following the
 * currently selected one.
 */
function selectNextTab() {
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);
  const activeTab = doc.getActiveTab();

  // Find the index of the currently active tab.
  let activeTabIndex = -1;
  for (let i = 0; i < allTabs.length; i++) {
    if (allTabs[i].getId() === activeTab.getId()) {
      activeTabIndex = i;
    }
  }

  // Update the user's selected tab if there is a valid next tab.
  const nextTabIndex = activeTabIndex + 1;
  if (nextTabIndex < allTabs.length) {
    doc.setActiveTab(allTabs[nextTabIndex].getId());
  }
}