Estensione di Documenti Google

Google Apps Script ti consente di creare e modificare programmaticamente 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 gli conferisce capacità speciali per modificare l'interfaccia utente o rispondere quando il documento viene aperto. Per creare uno script associato al contenitore da Documenti Google, fai clic su Estensioni > Apps Script.

In entrambi i casi, è semplice interagire con un documento Google Docs tramite il servizio Document 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, quindi recupera il foglio con ID t.0 (il primo foglio predefinito), inserisce un paragrafo che contiene lo stesso testo del nome del documento, applica uno stile di intestazione al paragrafo e aggiunge una tabella in base ai valori di un array bidimensionale. Lo script potrebbe apportare 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 (associati al contenitore), utilizza DocumentApp.getActiveDocument() e Document.getActiveTab().

Struttura di un documento

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

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

Gli elementi mostrati in grassetto possono essere inseriti; gli elementi non in grassetto possono essere manipolati solo sul posto.

Sostituzione del testo

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 tu voglia generare un documento Google personalizzato per ciascun cliente. Questo tipo di operazione viene spesso chiamato unione di posta.

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à delle espressioni regolari di JavaScript. La prima funzione riportata di seguito aggiunge 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 queste funzioni utilizzano i metodi getActiveDocument() e getActiveTab(), che si applicano solo agli script creati all'interno di un documento Google Docs; in uno script autonomo, utilizza DocumentApp.create(), openById() o openByUrl(), in combinazione con Document.getTab().

Aggiungere 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 personalizzati

Puoi personalizzare Documenti Google aggiungendo menu, finestre di dialogo e barre laterali. Tieni presente, tuttavia, 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 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 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 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 pubblicare lo script 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 per Documenti.

Trigger

Gli script associati a un documento Google possono utilizzare un trigger semplice 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, scrivi una funzione chiamata onOpen(). Per un esempio di questo trigger, vedi Menu personalizzati in Google Workspace. Sebbene il trigger semplice sia utile per aggiungere menu, non può utilizzare servizi Apps Script che richiedono l'autorizzazione.