Estensione di Documenti Google

Google Apps Script ti consente di creare e modificare documenti Google in modo programmatico e 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 generici: qualsiasi script può creare o modificare un documento se l'utente dispone delle autorizzazioni appropriate per il documento e uno script può anche essere associato a un documento, il che conferisce allo script capacità speciali di modificare l'interfaccia utente o rispondere all'apertura del documento. Per creare uno script vincolato a un container dall'interno di Documenti Google, fai clic su Estensioni > Apps Script.

In entrambi i casi, è semplice interagire con un documento Google tramite il Servizio documenti di Apps Script, come illustrato nell'esempio seguente.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.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 precedente crea un nuovo documento nel Google Drive dell'utente, quindi inserisce un paragrafo che contiene lo stesso testo del nome del documento, applica uno stile al paragrafo come intestazione e aggiunge una tabella in base ai valori in 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 (associato al container), utilizza DocumentApp.getActiveDocument().

Struttura di un documento

Dal punto di vista di Apps Script, un documento Google è strutturato in modo molto simile a un documento HTML, ovvero un documento Google è composto da elementi (come Paragraph o Table) che spesso contengono altri elementi. La maggior parte degli script che modificano un documento Google inizia con una chiamata a getBody(), poiché Body è un elemento principale che contiene tutti gli altri elementi tranne HeaderSection, FooterSection e qualsiasi Footnotes.

Tuttavia, esistono regole che stabiliscono quali tipi di elementi possono contenere altri tipi. Inoltre, il servizio documenti in Apps Script può inserire solo alcuni tipi di elementi. La struttura ad albero seguente mostra quali elementi possono essere contenuti da un determinato tipo di elemento.

Gli elementi mostrati in grassetto possono essere inseriti; quelli non in grassetto possono essere solo manipolati.

Sostituzione del testo

Apps Script viene spesso utilizzato per sostituire del testo in Documenti Google. Supponiamo che tu abbia un foglio di lavoro pieno di informazioni sul cliente e voglia generare un documento Google personalizzato per ciascun client. Questo tipo di operazione viene spesso denominato 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 consente di aggiungere diverse righe di testo segnaposto a un file di Documenti Google. Nel mondo reale, è più probabile che tu debba digitare i segnaposto nel documento. La seconda funzione sostituisce i segnaposto con proprietà definite nell'oggetto client.

Tieni presente che entrambe le funzioni utilizzano il metodo getActiveDocument(), che si applica solo agli script creati all'interno di un documento Google. In uno script autonomo, utilizza invece DocumentApp.create(), openById() o openByUrl().

Aggiungi alcuni segnaposto

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

Sostituisci i segnaposto

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .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);
}

Interfacce utente e menu personalizzati

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

Scopri come aggiungere menu personalizzati e finestre di dialogo in Documenti Google. Per ulteriori informazioni sulla creazione di interfacce personalizzate per una finestra di dialogo o una barra laterale, consulta la guida a HTML Service. Se prevedi di pubblicare la tua interfaccia personalizzata come parte 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 all'interno di 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 tutti, Apps Script ti consente di publish come componente aggiuntivo in modo che altri utenti possano installarlo dallo store dei componenti aggiuntivi.

Per informazioni su come creare un componente aggiuntivo per Documenti Google, consulta la guida rapida per la creazione di componenti aggiuntivi di Documenti.

Trigger

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

Per configurare l'attivatore, scrivi semplicemente una funzione denominata onOpen(). Per un esempio di questo attivatore, vedi Menu personalizzati in Google Workspace. Sebbene il trigger semplice sia utile per l'aggiunta di menu, non può utilizzare servizi Apps Script che richiedono l'autorizzazione.