Estensione di Documenti Google

Google Apps Script ti consente di creare e modificare in modo programmatico Documenti Google, nonché di personalizzare l'interfaccia utente con nuovi menu, finestre di dialogo e barre laterali.

Nozioni di base

Apps Script può interagire con Documenti Google in due modi generali: qualsiasi script può creare o modificare un documento se l'utente dello script dispone delle autorizzazioni appropriate per il documento e uno script può anche essere associato a un documento, il che conferisce allo script capacità speciali per modificare l'interfaccia utente o rispondere all'apertura del documento. Per creare uno script associato a un contenitore da Documenti Google, fai clic su Estensioni > Apps Script.

In entrambi i casi, è facile interagire con un documento di Documenti Google tramite il Document Service di Apps Script, come dimostra l'esempio seguente.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

Lo script riportato sopra crea un nuovo documento in Google Drive dell'utente, poi recupera la scheda con ID t.0 (la prima scheda predefinita), inserisce un paragrafo contenente lo stesso testo del nome del documento, imposta lo stile del paragrafo come intestazione e aggiunge una tabella in base ai valori di un array bidimensionale. Lo script potrebbe apportare facilmente queste modifiche a un documento esistente sostituendo la chiamata a DocumentApp.create() con DocumentApp.openById() o openByUrl(). Per gli script creati all'interno di un documento (vincolati al contenitore), utilizza DocumentApp.getActiveDocument() e Document.getActiveTab().

Struttura di un documento

Dal punto di vista di Apps Script, un documento di Documenti Google è strutturato molto come un documento HTML, ovvero è composto da uno o più oggetti Tab, ciascuno dei quali contiene elementi (come Paragraph o Table) che spesso contengono altri elementi. La maggior parte degli script che modificano un documento di Documenti Google inizia con una chiamata a getTab() e asDocumentTab() followed by getBody(), perché Body è un elemento di base che contiene tutti gli altri elementi in una scheda, ad eccezione di HeaderSection, FooterSection e qualsiasi Footnotes.

Tuttavia, esistono regole che indicano quali tipi di elementi possono contenere altri tipi. Inoltre, il servizio Document in Apps Script può inserire solo determinati tipi di elementi in altri elementi. L'albero riportato di seguito mostra quali elementi possono essere contenuti da un determinato tipo di elemento.

Gli elementi in grassetto possono essere inseriti, mentre quelli non in grassetto possono essere manipolati solo in situ.

Sostituzione del testo

Apps Script viene spesso utilizzato per sostituire il testo in Documenti Google. Supponiamo che tu abbia un foglio di lavoro contenente informazioni sui clienti e che tu voglia generare un Documenti Google personalizzato per ogni cliente. Questo tipo di operazione è spesso chiamato 'unione dinamica'.

Esistono molti modi per sostituire il testo, ma il più semplice è il metodo replaceText() mostrato nell'esempio seguente. replaceText supporta la maggior parte delle funzionalità di espressione regolare di JavaScript. La prima funzione riportata di seguito aggiunge diverse righe di testo segnaposto a un documento Google Docs. Nella vita reale, è più probabile che tu digiti i segnaposto nel documento. La seconda funzione sostituisce i segnaposto con le proprietà definite nell'objeto client.

Tieni presente che entrambe queste funzioni utilizzano i metodi getActiveDocument() e getActiveTab() che si applicano solo agli script creati all'interno di un documento di Documenti Google. In uno script autonomo, utilizza DocumentApp.create(), openById() o openByUrl(), combinati con Document.getTab().

Aggiungi alcuni segnaposto

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

Sostituisci i segnaposto

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

Menu e interfacce utente personalizzate

Puoi personalizzare Documenti Google aggiungendo menu, finestre di dialogo e barre laterali. Tieni presente, però, che uno script può interagire con l'interfaccia utente solo per l'istanza corrente di un documento aperto e solo se è legato al documento.

Scopri come aggiungere menu e finestre di dialogo personalizzati ai tuoi documenti Google. Per scoprire di più sulla creazione di interfacce personalizzate per una finestra di dialogo o una barra laterale, consulta la guida al servizio HTML. Se prevedi di pubblicare l'interfaccia personalizzata all'interno di un componente aggiuntivo, segui la guida di stile per garantire la coerenza con lo stile e il layout dell'editor di Documenti Google.

Componenti aggiuntivi per Documenti Google

I componenti aggiuntivi vengono eseguiti in Documenti Google e possono essere installati dallo store dei componenti aggiuntivi di Documenti Google. Se hai sviluppato uno script per Documenti Google e vuoi condividerlo con il mondo, Apps Script ti consente di pubblicarlo come componente aggiuntivo in modo che altri utenti possano installarlo dallo store dei componenti aggiuntivi.

Per scoprire come creare un componente aggiuntivo per Documenti Google, consulta la guida introduttiva alla creazione di componenti aggiuntivi di Documenti.

Trigger

Gli script associati a un documento Google possono utilizzare un attivatore semplice per rispondere all'evento onOpen del documento, che si verifica ogni volta che un utente che dispone dell'accesso in modifica al documento lo apre in Documenti Google.

Per configurare l'attivatore, basta scrivere una funzione chiamata onOpen(). Per un esempio di questo attivatore, vedi Menu personalizzati in Google Workspace. Sebbene l'attivatore semplice sia utile per aggiungere menu, non può utilizzare i servizi Apps Scripts che richiedono l'autorizzazione.