Estensione di Documenti Google

Google Apps Script ti consente di creare e modificare i documenti Google in modo programmatico, 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 principali: 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, in modo che lo script possa modificare l'interfaccia utente o rispondere quando viene aperto il documento. Per creare uno script associato a un container da 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 dimostra l'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 riportato sopra crea un nuovo documento nel Google Drive dell'utente, quindi inserisce un paragrafo che contiene lo stesso testo del nome del documento, definisce il paragrafo come intestazione e aggiunge una tabella basata sui valori in un array bidimensionale. Lo script potrebbe apportare altrettanto 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 (legato 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 è 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(), perché Body è un elemento principale che contiene tutti gli altri elementi tranne HeaderSection, FooterSection ed eventuali Footnotes.

Esistono però delle regole su 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 riportata di seguito mostra quali elementi possono essere contenuti da un determinato tipo di elemento.

Gli elementi mostrati in grassetto possono essere inseriti. Gli elementi non in grassetto possono essere manipolati solo al posto.

Sostituzione del testo in corso...

Apps Script viene spesso utilizzato per sostituire il testo in Documenti Google. Supponiamo che tu abbia un foglio di lavoro pieno di informazioni sui clienti e che voglia generare un documento Google personalizzato per ciascun cliente. (Questo tipo di operazione viene 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 consente di aggiungere diverse righe di testo segnaposto a un documento Google; nel mondo reale, è più probabile che tu digiti i segnaposto nel documento. La seconda funzione sostituisce i segnaposto con le 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);
}

Menu e interfacce utente personalizzati

Puoi personalizzare i documenti Google aggiungendo menu, finestre di dialogo e barre laterali. Tieni presente, tuttavia, che uno script può interagire con la UI solo per l'istanza corrente di un documento aperto e solo se lo script è legato al documento.

Scopri come aggiungere menu personalizzati e finestre di dialogo a Documenti Google. Per saperne di più 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 agli stili per 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 scoprire 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 il trigger, è sufficiente scrivere una funzione denominata onOpen(). Per un esempio di questo attivatore, vedi Menu personalizzati in Google Workspace. Sebbene il semplice trigger sia utile per aggiungere menu, non può utilizzare servizi Apps Script che richiedono autorizzazione.