Estendi di Documenti Google

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

In entrambi i casi, puoi interagire con un documento Google utilizzando il servizio Documenti di Apps Script, come dimostrato nell'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 precedente crea un nuovo documento in Google Drive dell'utente, quindi recupera la scheda con ID t.0 (la prima scheda predefinita), 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 di un array bidimensionale. Lo script potrebbe apportare queste modifiche anche 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 Docs è strutturato in modo simile a un documento HTML, ovvero un documento è composto da uno o più oggetti Tab, ognuno dei quali contiene elementi (come un Paragraph o un Table) che spesso contengono altri elementi. La maggior parte degli script che modificano un documento Documenti inizia con una chiamata a getTab e asDocumentTab seguita da getBody, perché Body è un elemento principale che contiene tutti gli altri elementi in 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. Il seguente albero 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.

Sostituisci testo

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

Puoi sostituire il testo utilizzando il metodo replaceText, che supporta la maggior parte delle funzionalità delle espressioni regolari JavaScript. Nell'esempio seguente, la prima funzione aggiunge un testo segnaposto al documento, mentre la seconda sostituisce questo testo con le proprietà di un oggetto client.

Entrambe queste funzioni utilizzano i metodi getActiveDocument e getActiveTab, che si applicano solo agli script creati all'interno di un documento Documenti; 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 aggiungendo menu personalizzati, finestre di dialogo e barre laterali. Tieni presente che uno script può interagire solo con l'interfaccia utente del documento a cui è associato.

Per saperne di più sulla creazione di interfacce personalizzate con HTML e CSS, consulta la guida al servizio HTML. Se prevedi di pubblicare la tua interfaccia come componente aggiuntivo, segui la guida di stile per assicurarti che il suo aspetto sia coerente con l'editor di documenti.

Componenti aggiuntivi per Documenti

I componenti aggiuntivi vengono eseguiti all'interno di Documenti e possono essere installati dallo store di componenti aggiuntivi di Documenti. Se hai sviluppato uno script per Documenti 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 di componenti aggiuntivi.

Per creare un componente aggiuntivo per Documenti, 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.

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