Lavorare con le schede

Apps Script per Documenti Google ti consente di accedere ai contenuti da qualsiasi scheda del documento.

Che cosa sono le schede?

Documenti Google presenta un livello organizzativo chiamato schede. Documenti consente agli utenti di creare una o più schede all'interno di un singolo documento, in modo simile a come esistono attualmente le schede in Fogli. Ogni scheda ha un proprio titolo e un ID (aggiunto nell'URL). Una scheda può avere anche schede secondarie, ovvero schede nidificate sotto un'altra scheda.

Schede di accesso

Le proprietà e i contenuti delle schede sono accessibili con Document.getTabs(), che restituisce un elenco di Tab. Le sezioni successive forniscono una breve panoramica della classe Tab. La documentazione della classe Tab fornisce anche informazioni più dettagliate.

Proprietà scheda

Le proprietà delle schede possono essere recuperate utilizzando metodi come Tab.getId() e Tab.getTitle().

Contenuti della scheda

I contenuti del documento all'interno di ogni scheda possono essere recuperati utilizzando Tab.asDocumentTab(). La sezione Modifiche alla struttura della classe di documento descrive come può essere utilizzata.

Gerarchia delle schede

Le schede secondarie sono esposte in Google Apps Script tramite Tab.getChildTabs(). Per accedere ai contenuti da tutte le schede è necessario attraversare la "struttura ad albero" delle schede secondarie. Ad esempio, considera un documento che contiene una gerarchia di schede come segue:

UI dell'elenco a schede contenente tre schede di primo livello, alcune delle quali hanno schede secondarie

Per accedere alla scheda 3.1.2, puoi procedere nel seguente modo:

// 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 i blocchi di codice di esempio nelle sezioni successive, che forniscono codice di esempio per eseguire l'iterazione su tutte le schede di un documento.

Altri modi per recuperare le schede

Esistono altri due modi per recuperare le schede:

  • Document.getTab(tabId): restituisce la scheda con l'ID specificato.
  • Document.getActiveTab(): restituisce la scheda attiva dell'utente. Funziona solo negli script legati a un documento. Le sezioni successive descrivono questo aspetto in modo più dettagliato.

Modifiche alla struttura della classe di documenti

In passato, i documenti non avevano il concetto di schede, quindi la classe Document espose metodi per accedere direttamente e modificare i contenuti di testo del documento. In questa categoria rientrano i seguenti metodi:

Con l'ulteriore gerarchia strutturale delle schede, questi metodi non rappresentano più semanticamente i contenuti testuali di tutte le schede del documento. I contenuti di testo ora verranno rappresentati in un livello diverso. Tutti i metodi di testo sopra menzionati sono accessibili tramite DocumentTab.

Questi metodi esistenti nella classe Document accedono o modificano i contenuti dalla scheda attiva (negli script associati a un determinato documento) o dalla prima scheda (se una scheda attiva non è disponibile).

Accedere ai contenuti di testo all'interno di una scheda specifica

Anziché utilizzare i metodi di testo esterni a Document, ti consigliamo di usare i metodi disponibili al di fuori della classe DocumentTab (disponibile tramite il metodo Tab.asDocumentTab()). Ad esempio:

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

Modifiche alla selezione dell'utente

Metodi di selezione del testo

La classe Document fornisce getter e setter per gestire la parte di testo selezionata dall'utente all'interno del documento attivo. Questi metodi operano nel contesto della scheda Attiva dell'utente che esegue lo script.

  • Document.getCursor(): restituisce la posizione del cursore dell'utente nella scheda attiva.
  • Document.getSelection(): restituisce l'intervallo di selezione dell'utente nella scheda attiva.
  • Document.setCursor(position): imposta la posizione del cursore dell'utente nel documento attivo. Se la posizione si trova in una scheda non attiva, anche la scheda attiva dell'utente viene commutata nella scheda associata a quella posizione.
  • Document.setSelection(range): imposta l'intervallo di selezione dell'utente nel documento attivo. Se l'intervallo si trova in una scheda non attiva, anche la scheda attiva dell'utente viene commutata nella scheda associata a quell'intervallo.

Metodi di selezione delle schede e casi d'uso

Con l'introduzione delle schede, può essere utile ottenere e impostare la scheda attiva dell'utente che esegue lo script. Questa operazione può essere eseguita utilizzando i seguenti metodi:

La "selezione" olistica dell'utente è costituita da una combinazione della scheda attiva insieme alla posizione corrente del cursore o all'intervallo di selezione. I due modi per lavorare con una selezione attiva sono modificare esplicitamente la scheda attiva dell'utente in una scheda specifica o utilizzare la scheda attiva dell'utente.

La modifica esplicita della scheda Attiva dell'utente può essere effettuata utilizzando Document.setActiveTab(tabId). In alternativa, chiamando Document.setCursor(position) o Document.setSelection(range) con un Position o Range da una scheda inattiva, la scheda diventerà attiva.

Se il comportamento previsto dello script prevede l'utilizzo della scheda attiva dell'utente senza modificarla, Document.setActiveTab(tabId) non è necessario. I metodi Document.getCursor() e Document.getSelection() opereranno già sulla scheda attiva, in base alla scheda da cui l'utente esegue lo script.

Tieni presente che un documento non supporta più selezioni di schede o più posizioni o intervalli in schede diverse. Di conseguenza, se utilizzi Document.setActiveTab(tabId), la posizione precedente del cursore o l'intervallo di selezione verranno cancellati.

Metodi di posizione e intervallo per una scheda specifica

La scheda specifica è ciò che dà il significato ai concetti di selezione del testo di Position e Range. In altre parole, una posizione del cursore o un intervallo di selezione sono significativi solo se lo script conosce la scheda specifica in cui si trova la posizione o l'intervallo.

Questo risultato viene ottenuto utilizzando i metodi DocumentTab.newPosition(element, offset) e DocumentTab.newRange(), che costruiscono una posizione o un intervallo che ha come target il DocumentTab specifico da cui viene chiamato il metodo. Al contrario, Document.newPosition(element, offset) e Document.newRange() costruiranno una posizione o un intervallo che ha come target la scheda attiva (o la prima scheda, se lo script non è vincolato).

Consulta i blocchi di codice di esempio nelle sezioni successive, che forniscono codice di esempio per lavorare con le selezioni.

Pattern di utilizzo comuni per le schede

I seguenti esempi di codice descrivono vari modi per interagire con le schede.

Leggere i contenuti di tutte le schede del documento

È possibile eseguire la migrazione del codice esistente che aveva eseguito questa operazione prima della funzionalità delle schede per supportare le schede spostando la struttura ad albero e chiamando i metodi getter da Tab e DocumentTab anziché da Document. Il seguente esempio di codice parziale mostra come stampare tutti i contenuti di testo da ogni scheda di un documento. Questo codice di traversale delle schede può essere adattato a molti altri casi d'uso che non richiedono la struttura effettiva delle schede.

/** 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);
  }
}

Leggi i contenuti della scheda dalla prima scheda nel documento

Questa operazione è simile alla lettura di tutte le schede.

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

Aggiorna i contenuti della scheda nella prima scheda

Il seguente esempio di codice parziale mostra come scegliere come target una scheda specifica quando apporti aggiornamenti.

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

Aggiorna i contenuti della scheda nella scheda attiva o selezionata

Il seguente esempio di codice parziale mostra come scegliere come target la scheda attiva quando si apportano aggiornamenti.

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

Impostare una posizione del cursore o un intervallo di selezione nella scheda attiva

Il seguente esempio di codice parziale mostra come aggiornare la posizione del cursore o l'intervallo di selezione all'interno della scheda Attiva dell'utente. Questo è rilevante solo negli script vincolati.

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

Impostare la scheda attiva o selezionata

Il seguente esempio di codice parziale mostra come modificare la scheda attiva dell'utente. Questo è rilevante solo negli script vincolati.

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