Apps Script per Documenti Google ti consente di accedere ai contenuti da qualsiasi scheda nel 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 sono presenti schede in Fogli. Ogni scheda ha il proprio titolo e un ID (aggiunto nell'URL). Una scheda può anche avere schede secondarie, ovvero nidificate sotto un'altra scheda.
Il supporto API per le schede secondarie è già disponibile, ma il supporto UI sarà disponibile a breve. Oggi puoi gestire le schede figlio nel tuo codice in modo che quando verrà lanciato il supporto della UI non dovrai aggiornare il codice.
Accedi alle schede
Le proprietà e i contenuti delle schede sono accessibili tramite
Document.getTabs()
,
che restituisce un elenco di Tab
. Le sezioni successive forniscono una breve panoramica
Tab
corso; la documentazione della classe Tab
fornisce anche informazioni più dettagliate.
Proprietà scheda
Le proprietà della scheda possono essere recuperate utilizzando metodi come
Tab.getId()
e
Tab.getTitle()
.
Contenuti della scheda
I contenuti dei documenti all'interno di ciascuna scheda possono essere recuperati utilizzando
Tab.asDocumentTab()
Le modifiche alla struttura del corso sui documenti
in cui viene descritto come utilizzare questa funzionalità.
Gerarchia delle schede
Le schede secondarie sono esposte in Google Apps Script tramite
Tab.getChildTabs()
L'accesso ai contenuti da tutte le schede richiede di attraversare la struttura ad albero di schede secondarie.
Ad esempio, considera un documento che contiene una gerarchia di schede come segue:
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());
Nelle sezioni successive, consulta i blocchi di codice di esempio, che forniscono un codice campione per usando l'iterazione in 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. Compatibile solo in script legati a un documento. La sezioni successive lo descrivono in modo più dettagliato.
Modifiche alla struttura delle classi del documento
In passato, i documenti non avevano il concetto di schede, quindi la classe Documento metodi esposti per accedere direttamente ai contenuti testuali del documento e modificarli. In questa categoria rientrano i seguenti metodi:
Document.addBookmark(position)
Document.addFooter()
Document.addHeader()
Document.addNamedRange(name, range)
Document.getBody()
Document.getBookmark(id)
Document.getBookmarks()
Document.getFooter()
Document.getFootnotes()
Document.getHeader()
Document.getNamedRangeById(id)
Document.getNamedRanges()
Document.getNamedRanges(name)
Document.newPosition(element, offset)
Document.newRange()
Con l'ulteriore gerarchia strutturale delle schede, questi metodi non
rappresentare semanticamente i contenuti testuali di tutte le schede del documento. Il testo
i contenuti saranno ora rappresentati in un livello diverso; tutte le funzionalità
i metodi di testo sono accessibili tramite DocumentTab
.
Questi metodi esistenti nella classe Document
consentiranno di accedere ai contenuti o modificarli
dalla scheda Attiva (negli script associati a un
documento specifico) o la prima scheda (se una scheda attiva non è disponibile).
Accedere ai contenuti testuali di una scheda specifica
Invece di utilizzare i metodi di testo diversi da Document
, ti consigliamo di usare
i metodi disponibili fuori dalla classe DocumentTab
(che è
disponibili tramite
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 posizione nel testo
selezionata dall'utente, all'interno del documento attivo. Questi metodi operano all'interno
il 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 è in una scheda non attiva, anche la scheda attiva dell'utente viene spostata nella scheda associata con quella posizione.Document.setSelection(range)
: Imposta l'intervallo di selezione dell'utente nel documento attivo. Se l'intervallo è compreso in un scheda non attiva, anche la scheda attiva dell'utente viene spostata nella scheda associata con quell'intervallo.
Metodi di selezione delle schede e casi d'uso
Con l'introduzione delle schede, può essere utile recuperare e impostare la scheda attiva l'utente che esegue lo script. Questa operazione può essere eseguita utilizzando i seguenti metodi:
Document.getActiveTab()
: Restituisce il valoreTab
attivo dell'utente nel documento attivo.Document.setActiveTab(tabId)
: Imposta ilTab
selezionato dall'utente nel documento corrente sulla scheda con l'ID specificato.
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 pattern per lavorare con una selezione attiva consiste nel modificare esplicitamente 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, la chiamata
Document.setCursor(position)
oppure Document.setSelection(range)
con Position
o Range
di una scheda non attiva, la scheda verrà ripristinata
attivo.
Se il comportamento previsto dello script è l'utilizzo della scheda attiva dell'utente
senza modificarlo,
Document.setActiveTab(tabId)
non è necessaria. La
Document.getCursor()
e Document.getSelection()
funzioneranno già sulla scheda Attiva, in base alla scheda
da cui l'utente sta eseguendo lo script.
Tieni presente che un documento non supporta la selezione di più schede o più schede.
posizioni o intervalli aggiuntivi in diverse schede. Di conseguenza, l'uso
Document.setActiveTab(tabId)
cancella la posizione precedente del cursore o l'intervallo di selezione.
Metodi di posizione e intervallo per una scheda specifica
La scheda specifica è ciò che dà significato ai concetti di selezione del testo
Position
e Range
. In altre parole, la posizione del cursore o un intervallo di selezione
sono significative solo se lo script conosce la scheda specifica che la posizione o
l'intervallo di date è compreso.
A questo scopo, utilizza
DocumentTab.newPosition(element, offset)
e
DocumentTab.newRange()
che costruiscono una posizione o un intervallo che ha come target uno specifico
DocumentTab
da cui viene chiamato il metodo. Al contrario,
Document.newPosition(element, offset)
e Document.newRange()
costruisce una posizione o un intervallo che ha come target la scheda attiva (o la prima
, se lo script non è vincolato).
Nelle sezioni successive, consulta i blocchi di codice di esempio, che forniscono un codice campione per lavorare con le selezioni.
Modelli di utilizzo comuni per le schede
I seguenti esempi di codice descrivono le varie modalità di interazione con le schede.
Leggi i contenuti delle schede di tutte le schede del documento
È possibile eseguire la migrazione del codice esistente che ha eseguito questa operazione prima della funzionalità delle schede per l'assistenza
schede attraverso la struttura ad albero delle schede e richiamando metodi getter da Tab
e
DocumentTab
anziché Document
. Il seguente esempio di codice parziale mostra come
per stampare tutti i contenuti del testo di ogni scheda di un documento. Questa scheda
il codice di attraversamento può essere adattato per molti altri casi d'uso che non
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 crei 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 crei 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(); }
Imposta 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 dell'intervallo di selezione nella scheda Attiva dell'utente. È pertinente solo nei limiti script.
/** * 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 è pertinente solo negli script associati.
/** * 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()); } }