Trigger per i componenti aggiuntivi Editor

I trigger di Apps Script fanno in modo che una funzione script specificata (la funzione di trigger) venga eseguita ogni volta che si verifica un evento specifico. Solo determinati eventi possono attivare gli attivatori e ogni applicazione Google Workspace supporta un insieme diverso di eventi.

Quando viene attivato un attivatore, viene creato un oggetto evento. Questa struttura JSON contiene dettagli sull'evento che si è verificato. Le informazioni nella struttura dell'oggetto evento sono organizzate in modo diverso in base al tipo di attivatore.

Una volta creato l'oggetto evento, Apps Script lo passa come parametro alla funzione di attivazione. La funzione di trigger è una funzione di callback che devi implementare autonomamente per eseguire le azioni appropriate per rispondere all'evento. Ad esempio, in un componente aggiuntivo di Editor un attivatore viene utilizzato per creare voci di menu del componente aggiuntivo quando viene aperto un documento. In questo caso, implementa la funzione di attivazione onOpen(e) per creare gli elementi del menu di cui il componente aggiuntivo necessita, eventualmente utilizzando i dati nell'oggetto evento.

Questa pagina fornisce linee guida per l'utilizzo degli attivatori nei progetti di componenti aggiuntivi dell'editor.

Tipi di attivatori dei componenti aggiuntivi dell'editor

Puoi utilizzare la maggior parte dei tipi di trigger generici disponibili per i progetti Apps Script nei componenti aggiuntivi di Editor, inclusi i trigger semplici e la maggior parte dei trigger installabili. L'insieme esatto di tipi di attivatori disponibili dipende dall'applicazione estesa.

La tabella seguente mostra i tipi di attivatori semplici e installabili che possono essere utilizzati dai componenti aggiuntivi di Editor e fornisce i link agli oggetti evento corrispondenti:

Evento	Oggetto evento	Trigger semplici	Trigger installabili
Apri Si apre un file dell'editor.	Oggetto evento onOpen di Documenti Oggetto evento onOpen di Moduli Oggetto evento onOpen di Fogli Oggetto evento onOpen di Presentazioni	Documenti Moduli* Fogli Presentazioni function onOpen(e)	Documenti Moduli Fogli
Installa Il componente aggiuntivo è installato.	Objecto evento onInstall	Documenti Moduli Fogli Presentazioni function onInstall(e)
Modifica I contenuti delle celle del foglio di lavoro vengono modificati.	Objecto evento onEdit di Fogli	Fogli function onEdit(e)	Fogli
Modifica I contenuti di un foglio vengono modificati o formattati.	Objecto evento onChange di Fogli		Fogli
Form-submit Un modulo Google è stato inviato.	Oggetto evento di invio modulo di Moduli Oggetto evento di invio modulo di Fogli		Moduli Fogli
In base al tempo (orologio) L'attivatore viene attivato in un momento o a un intervallo specificato.	Oggetto evento basato sul tempo		Documenti Moduli Fogli Presentazioni

* L'evento open per Moduli Google non si verifica quando un utente apre un modulo per rispondere, ma quando un editor lo apre per modificarlo.

Trigger semplici nei componenti aggiuntivi

Gli attivatori semplici utilizzano un insieme di nomi di funzioni riservate, non possono utilizzare servizi che richiedono l'autorizzazione e vengono attivati automaticamente per l'utilizzo. In alcuni casi, un evento di trigger semplice può essere gestito da un trigger installabile.

Puoi aggiungere un semplice attivatore a un componente aggiuntivo semplicemente implementando una funzione con uno dei seguenti nomi riservati:

• onOpen(e) viene eseguito quando un utente apre un documento, un foglio di lavoro o una presentazione. onOpen(e) può essere eseguito anche quando un modulo viene aperto nell'editor (ma non quando si risponde al modulo). Viene eseguito solo se l'utente ha l'autorizzazione per modificare il file in questione e viene utilizzato più spesso per creare elementi di menu.
• onInstall(e) viene eseguito quando un utente installa un componente aggiuntivo. In genere, onInstall(e) viene utilizzato solo per chiamare onOpen(e); in questo modo, i menu dei componenti aggiuntivi vengono visualizzati immediatamente dopo l'installazione senza che l'utente debba aggiornare la pagina.
• onEdit(e) viene eseguito quando un utente modifica il valore di una cella in un foglio di lavoro. Questo attivatore non viene attivato in risposta a spostamenti, formattazione o altre modifiche delle celle che non ne alterano i valori.

Restrizioni

Gli attivatori semplici nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano gli attivatori semplici in altri tipi di progetti Apps Script. Tieni particolarmente presente queste limitazioni quando progetti i componenti aggiuntivi:

• Gli attivatori semplici non vengono eseguiti se un file viene aperto in modalità di sola lettura (visualizzazione o commento). Questo comportamento impedisce il completamento dei menu dei componenti aggiuntivi.
• In alcuni casi, i componenti aggiuntivi di Editor eseguono i trigger semplici onOpen(e) e onEdit(e) in una modalità senza autorizzazione. Questa modalità presenta alcune complicazioni aggiuntive, come descritto nel modello di autorizzazione dei componenti aggiuntivi.
• Gli attivatori semplici non possono utilizzare servizi o eseguire altre azioni che richiedono autorizzazione, tranne come indicato nel modello di autorizzazione dei componenti aggiuntivi.
• Gli attivatori semplici non possono essere eseguiti per più di 30 secondi. Cerca di minimizzare la quantità di elaborazione eseguita in una semplice funzione di attivazione.
• Gli trigger semplici sono soggetti ai limiti di quota degli trigger di Apps Script.

Attivatori installabili nei componenti aggiuntivi

I componenti aggiuntivi possono creare e modificare tramite programmazione gli attivatori installabili con il servizio Script di Apps Script. Gli attivatori installabili dei componenti aggiuntivi non possono essere creati manualmente. A differenza degli attivatori semplici, gli attivatori installabili possono utilizzare servizi che richiedono l'autorizzazione.

Gli attivatori installabili nei componenti aggiuntivi non inviano email di errore all'utente quando si verificano errori, poiché nella maggior parte dei casi un utente non è in grado di risolvere il problema. Per questo motivo, se possibile, devi progettare il tuo componente aggiuntivo in modo che gestisca in modo corretto gli errori per conto dell'utente.

I componenti aggiuntivi possono utilizzare i seguenti attivatori installabili:

• Gli attivatori installabili Apri vengono eseguiti quando un utente apre un documento, un foglio di lavoro o un modulo nell'editor (ma non quando risponde al modulo).
• Gli attivatori installabili Modifica vengono eseguiti quando un utente modifica il valore di una cella in un foglio di lavoro. Questo attivatore non viene attivato in risposta alla formattazione o ad altre modifiche che non alterano i valori delle celle.
• Gli attivatori installabili Modifica vengono eseguiti quando un utente apporta una modifica a un foglio di lavoro, incluse le modifiche alla formattazione e al foglio di lavoro stesso (ad esempio l'aggiunta di una riga).

• Gli attivatori installabili Invio modulo vengono eseguiti quando viene inviata una risposta di Moduli Google.

• Gli attivatori basati sul tempo (chiamati anche attivatori dell'orologio) vengono attivati in un momento specifico o ripetutamente a intervalli regolari.

Autorizzazione degli trigger installabili

In genere, se uno sviluppatore aggiorna un componente aggiuntivo per utilizzare nuovi servizi che richiedono un'autorizzazione aggiuntiva, gli utenti vengono invitati a autorizzarlo di nuovo la volta successiva che lo utilizzano.

Tuttavia, i componenti aggiuntivi che utilizzano gli attivatori presentano problemi di autorizzazione speciali. Immagina un componente aggiuntivo che utilizza un attivatore per monitorare l'invio dei moduli: un creator di moduli potrebbe autorizzarlo la prima volta che lo utilizza, quindi lasciarlo in esecuzione per mesi o anni senza mai riaprire il modulo. Se lo sviluppatore del componente aggiuntivo aggiornasse il componente aggiuntivo per utilizzare nuovi servizi che richiedono un'autorizzazione aggiuntiva, il creator del modulo non vedrebbe mai la finestra di dialogo di riattivazione dell'autorizzazione perché non ha mai riaperto il modulo e il componente aggiuntivo non funzionerebbe più.

A differenza degli attivatori nei normali progetti Apps Script, gli attivatori nei plug-in continuano a essere attivati anche se richiedono una nuova autorizzazione. Tuttavia, lo script non va ancora a buon fine se incontra una riga di codice che richiede un'autorizzazione che lo script non ha. Per evitare questa situazione, gli sviluppatori possono utilizzare il metodo ScriptApp.getAuthorizationInfo() per limitare l'accesso a parti di codice che sono cambiate tra le versioni pubblicate del plug-in.

Di seguito è riportato un esempio della struttura consigliata da utilizzare nelle funzioni di attivazione per evitare problemi di autorizzazione. La funzione di attivazione di esempio risponde a un evento di invio del modulo all'interno di un componente aggiuntivo di Fogli Google e, se è necessaria la nuova autorizzazione, invia all'utente del componente aggiuntivo un'email di avviso utilizzando un modello HTML.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Restrizioni

Gli attivatori installabili nei componenti aggiuntivi sono soggetti alle stesse restrizioni che regolano gli attivatori installabili in altri tipi di progetti Apps Script.

Oltre a queste limitazioni, sono previste diverse limitazioni per gli attivatori installabili nei componenti aggiuntivi:

• Ogni componente aggiuntivo può avere un solo attivatore di ogni tipo, per utente e per documento. Ad esempio, in un determinato foglio di lavoro, un determinato utente può avere un solo attivatore di modifica, anche se nello stesso foglio di lavoro potrebbe avere anche un attivatore di invio del modulo o un attivatore basato sul tempo. Un altro utente con accesso allo stesso foglio di lavoro potrebbe avere un proprio insieme di attivatori separato.
• I componenti aggiuntivi possono creare attivatori solo per il file in cui vengono utilizzati. In altre parole, un componente aggiuntivo utilizzato nel documento Google A non può creare un attivatore per monitorare l'apertura del documento Google B.
• Gli attivatori basati sul tempo non possono essere eseguiti più di una volta all'ora.
• I componenti aggiuntivi non inviano automaticamente un'email all'utente quando il codice eseguito da un attivatore installabile genera un'eccezione. Spetta allo sviluppatore verificare e gestire in modo appropriato i casi di errore.
• Gli attivatori dei componenti aggiuntivi non vengono più attivati in una delle seguenti situazioni:
  • Se il componente aggiuntivo viene disinstallato dall'utente,
  • Se il componente aggiuntivo è disattivato in un documento (se viene riattivato, l'attivatore diventa di nuovo operativo) o
  • Se lo sviluppatore annulla la pubblicazione del componente aggiuntivo o invia una versione non funzionante allo store dei componenti aggiuntivi.
• Le funzioni di attivazione dei componenti aggiuntivi vengono eseguite finché non raggiungono il codice che utilizza un servizio non autorizzato, a quel punto si arrestano. Questo vale solo se il componente aggiuntivo è pubblicato. Lo stesso attivatore in un normale progetto Apps Script o in un componente aggiuntivo non pubblicato non viene eseguito se una parte dello script richiede l'autorizzazione.
• Gli attivatori installabili sono soggetti ai limiti di quota degli attivatori di Apps Script.