Trigger per i componenti aggiuntivi Editor

Gli attivatori di Apps Script causano uno script specificato (la funzione trigger) da eseguire ogni volta che un evento specificato . Solo alcuni eventi possono attivare gli attivatori e ogni L'applicazione Google Workspace supporta un insieme di eventi diverso.

Quando si attiva un attivatore, viene creato un oggetto evento. Questa struttura JSON contiene i dettagli dell'evento che si è verificato. Le informazioni presenti nell'evento struttura degli oggetti è organizzata in modo diverso in base al tipo di trigger.

Una volta creato l'oggetto evento, Apps Script lo passa come parametro al di trigger. La funzione trigger è una funzione di callback che devi mettere in atto personalmente le azioni necessarie per rispondere alle . Ad esempio, in un componente aggiuntivo Editor un trigger viene utilizzato per creare voci di menu aggiuntive all'apertura di un documento. In questo caso, implementa la funzione trigger onOpen(e) per creare le voci di menu del componente aggiuntivo le esigenze aziendali, magari usando i dati nell'oggetto evento.

Questa pagina fornisce le linee guida sull'utilizzo dei trigger in editor per i progetti aggiuntivi.

Tipi di trigger dei componenti aggiuntivi dell'editor

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

La tabella seguente mostra i tipi di trigger semplici e installabili che I componenti aggiuntivi dell'editor possono utilizzare e fornire link agli oggetti evento corrispondenti:

Evento	Oggetto evento	Trigger semplici	Trigger installabili
Apri Viene aperto un file editor.	Oggetto evento onOpen di Documenti Oggetto evento Forms onOpen 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.	Oggetto evento onInstall	Documenti Moduli Fogli Presentazioni function onInstall(e)
Modifica Il contenuto della cella del foglio di lavoro viene modificato.	Oggetto evento onEdit di Fogli	Fogli function onEdit(e)	Fogli
Modifica I contenuti di un foglio vengono modificati o formattati.	Oggetto evento onChange di Fogli		Fogli
Invio del modulo Viene inviato un modulo Google.	Oggetto evento modulo invio modulo Oggetto evento modulo di invio di Fogli		Moduli Fogli
A tempo (orologio) L'attivatore si attiva a un intervallo di tempo o a un intervallo specifico.	Oggetto evento a tempo		Documenti Moduli Fogli Diapositive

* L'evento di apertura di Moduli Google non si verifica quando un utente apre un modulo per rispondere, ma piuttosto quando un editor apre il modulo per modificarlo.

Trigger semplici nei componenti aggiuntivi

I trigger semplici utilizzano un insieme di valori riservati funzioni, non possono utilizzare servizi che richiedono l'autorizzazione e sono attivata automaticamente per l'uso. In alcuni casi, è sufficiente un semplice evento di trigger essere gestiti da un attivatore installabile.

Puoi aggiungere un semplice trigger a un componente aggiuntivo implementando semplicemente 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ò anche essere eseguito quando un modulo viene aperto nell'editor (ma non quando rispondi al modulo). Viene eseguita solo se l'utente ha autorizzazione necessaria per modificare il file in questione ed è spesso utilizzato per creare voci del menu.
• onInstall(e) viene eseguito quando un utente installa un componente aggiuntivo. Di solito a onInstall(e) è utilizzato solo per chiamare onOpen(e); in modo che i menu dei componenti aggiuntivi vengano subito dopo l'installazione senza richiedere all'utente di aggiornare la pagina.
• onEdit(e) viene eseguito quando un utente modifica il valore di una cella in un foglio di lavoro. Questo attivatore non si attiva in risposta a spostamenti di celle, formattazione o altre modifiche che non alterano i valori delle celle.

Restrizioni

I trigger semplici nei componenti aggiuntivi sono soggetti allo stesso limitazioni che regolano in altri tipi di progetti Apps Script. Prendi nota in particolare di questi aspetti delle limitazioni durante la progettazione dei componenti aggiuntivi:

• I trigger semplici non vengono eseguiti se un file viene aperto in sola lettura (visualizzazione o . Questo comportamento impedisce che i menu dei componenti aggiuntivi vengano compilati.
• In determinate circostanze, i componenti aggiuntivi Editor eseguono i propri file onOpen(e) e onEdit(e) si attiva in modo semplice in una modalità senza autorizzazione. Questa modalità presenta alcune complicazioni aggiuntive, come illustrato modello di autorizzazione aggiuntiva.
• I trigger semplici non possono utilizzare servizi o di altre azioni che richiedono autorizzazione, ad eccezione di descritto nel modello di autorizzazione aggiuntiva.
• I trigger semplici non possono essere eseguiti per più di 30 secondi. Fai attenzione a ridurre al minimo la quantità di elaborazione eseguita da una semplice funzione di trigger.
• I trigger semplici sono soggetti ai trigger di Apps Script limiti di quota.

Trigger installabili nei componenti aggiuntivi

I componenti aggiuntivi possono creare e modificare in modo programmatico i trigger installabili con il servizio Apps Script Script. componente aggiuntivo e non possono essere creati manualmente. A differenza dei semplici trigger, I trigger installabili possono usare servizi che richiedono l'autorizzazione.

Gli attivatori installabili nei componenti aggiuntivi non inviano email di errore quando riscontra errori, dato che nella maggior parte dei casi l'utente non è in grado per risolvere il problema. Per questo motivo, devi progettare il componente aggiuntivo gestire agevolmente gli errori per conto dell'utente quando possibile.

I componenti aggiuntivi possono utilizzare i seguenti attivatori installabili:

• Gli attivatori Apri installabili vengono eseguiti quando un utente apre un documento, foglio di lavoro oppure quando un modulo viene aperto nell'editor (ma non quando rispondi al modulo).
• Gli attivatori Modifica installabili vengono eseguiti quando un utente modifica il valore di una cella in una in un foglio di lavoro. Questo attivatore non si attiva in risposta a formattazione o altro modifiche che non alterano i valori delle celle.
• Gli attivatori installabili di modifica vengono eseguiti quando un utente apporta una qualsiasi modifica a un foglio di lavoro, incluse le modifiche di formattazione e quelle apportate stessa (ad esempio, aggiungendo una riga).

• Gli attivatori installabili Invio tramite modulo vengono eseguiti quando viene visualizzata una risposta di un modulo Google inviate.

• Trigger basati sul tempo (chiamati anche trigger orologio) si attivano a un'ora specifica o ripetutamente intervallo di tempo regolare.

Autorizzazione dei trigger installabili

Di solito, se uno sviluppatore aggiorna un componente aggiuntivo per usare nuovi servizi che richiedono agli utenti verrà chiesto di autorizzare di nuovo il componente aggiuntivo volta in cui lo usano.

Tuttavia, i componenti aggiuntivi che utilizzano i trigger devono affrontare sfide di autorizzazione speciali. Immagina un componente aggiuntivo che utilizza un attivatore per monitorare gli invii di un modulo: il creator può autorizzare il componente aggiuntivo la prima volta che lo utilizza e poi lasciarlo così per mesi o anni senza mai riaprire il modulo. Se lo sviluppatore del componente aggiuntivo dovesse aggiornare il componente aggiuntivo per l'utilizzo di nuovi servizi richiedono un'autorizzazione aggiuntiva, l'autore del modulo non vedrà mai finestra di dialogo di nuova autorizzazione perché non hanno mai riaperto il modulo e il componente aggiuntivo smetterà di funzionare.

A differenza dei trigger nei normali progetti Apps Script, gli attivatori continuano ad attivarsi anche se necessitano di una nuova autorizzazione. Tuttavia, lo script continua a non funzionare se colpisce una riga di codice che richiede l'autorizzazione, lo script non contiene. Per evitare questa situazione, gli sviluppatori possono usare il metodo ScriptApp.getAuthorizationInfo() per limitare l'accesso alle parti di codice che sono cambiate tra le versioni pubblicate il componente aggiuntivo.

Di seguito è riportato un esempio della struttura consigliata da utilizzare nelle funzioni di trigger per per evitare insidie legate alle autorizzazioni. La funzione di trigger di esempio risponde a un modulo di invio in un componente aggiuntivo di Fogli Google e, se la nuova autorizzazione è obbligatorio, invia all'utente del componente aggiuntivo un'email di avviso utilizzando il codice HTML basato su modelli.

/**
 * 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

I trigger installabili nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano i trigger installabili in altri tipi di progetti Apps Script.

Oltre a queste restrizioni, vengono applicate diverse limitazioni ai si attiva specificamente 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 utente può disporre di una sola modifica attivatore, anche se l'utente potrebbe avere anche un attivatore Invio modulo o un nello stesso foglio di lavoro. Un altro utente con accesso nello stesso foglio di lavoro potrebbero avere un insieme separato di attivatori.
• I componenti aggiuntivi possono creare trigger solo per il file in cui viene utilizzato. Ciò significa che un componente aggiuntivo utilizzato in Documenti Google non può creare un attivatore monitora l'apertura del documento Google B.
• I trigger a tempo non possono essere eseguiti più di una volta all'ora.
• I componenti aggiuntivi non inviano automaticamente un'email all'utente quando il codice viene eseguito da un il trigger installabile genera un'eccezione. Spetta allo sviluppatore controllare i casi di errore e la relativa gestione agevole.
• 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 torna operativa) o
  • Se lo sviluppatore annulla la pubblicazione del componente aggiuntivo o invia una versione non funzionante al store di componenti aggiuntivi.
• Le funzioni di attivazione dei componenti aggiuntivi vengono eseguite finché non raggiungono il codice che utilizza da un servizio non autorizzato, a cui vengono interrotti. Ciò vale solo se il componente aggiuntivo sia pubblicato; lo stesso trigger in un normale progetto Apps Script un componente aggiuntivo non pubblicato non viene eseguito se qualsiasi parte dello script richiede autorizzazione.
• I trigger installabili sono soggetti all'attivatore di Apps Script limiti di quota.