Trigger semplici

I trigger consentono ad Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento come l'apertura di un documento. I trigger semplici sono un insieme di funzioni riservate integrate in Apps Script, come la funzione onOpen(e), che viene eseguita quando un utente apre un file di Documenti, Fogli, Presentazioni o Moduli Google. Gli attivatori installabili offrono di più rispetto ai semplici trigger, ma deve essere attivata prima dell'uso. Per entrambi tipi di trigger, Apps Script passa la funzione attivata oggetto evento che contiene informazioni sul contesto in cui si è verificato l'evento.

Per iniziare

Per utilizzare un trigger semplice, è sufficiente creare una funzione che utilizzi uno di questi nomi di funzioni riservati:

  • onOpen(e) viene eseguito quando un utente apre un foglio di lavoro, un documento, una presentazione oppure modulo che l'utente è autorizzato a modificare.
  • onInstall(e) viene eseguito quando un utente installa Componente aggiuntivo Editor Documenti, Fogli, Presentazioni o Moduli Google.
  • onEdit(e) viene eseguito quando un utente modifica un valore in un foglio di lavoro.
  • onSelectionChange(e) viene eseguito quando un utente modifica la selezione in un foglio di lavoro.
  • doGet(e) viene eseguito quando un utente visita un'app web o un programma invia una richiesta GET HTTP a un'app web.
  • doPost(e) viene eseguito quando un programma invia una richiesta POST HTTP a un'app web.

Il parametro e nei nomi delle funzioni sopra indicati è un oggetto evento che viene passato all'oggetto personalizzata. L'oggetto contiene informazioni sul contesto che ha causato l'errore ma il suo utilizzo è facoltativo.

Restrizioni

Perché i semplici attivatori si attivano automaticamente senza chiedere all'utente autorizzati, sono soggetti a diverse restrizioni:

  • Lo script deve essere legato a un Fogli, Presentazioni, Documenti o Moduli oppure essere un componente aggiuntivo che estende uno dei per queste applicazioni.
  • Non vengono eseguiti se un file viene aperto in modalità di sola lettura (visualizzazione o commento).
  • Le esecuzioni degli script e le richieste API non causano l'esecuzione di trigger. Ad esempio: chiamata al numero Range.setValue() la modifica di una cella non causa l'esecuzione dell'attivatore onEdit del foglio di lavoro.
  • Non possono accedere ai servizi che richiedono autorizzazione. Ad esempio: un semplice attivatore non può inviare un'email perché Il servizio Gmail richiede l'autorizzazione, ma un semplice trigger può tradurre una frase con Servizio linguistico anonimo.
  • Possono modificare il file a cui sono associati, ma non possono accedere ad altri file perché sarebbe necessaria l'autorizzazione.
  • Potrebbe essere o meno in grado di determinare l'identità dell'utente corrente, in base a un insieme complesso di limitazioni di sicurezza.
  • Non possono essere pubblicati per più di 30 secondi.
  • In determinate circostanze, I componenti aggiuntivi di Editor eseguono i propri onOpen(e) e onEdit(e) semplici si attiva in una modalità senza autorizzazione che presenta alcune complicazioni aggiuntive. Per ulteriori informazioni, consulta guida al ciclo di vita dell'autorizzazione dei componenti aggiuntivi.
  • I trigger semplici sono soggetti ai trigger di Apps Script limiti di quota.

Queste limitazioni non si applicano a doGet(e) o doPost(e).

onOpen(e)

L'attivatore onOpen(e) viene eseguito automaticamente quando un utente apre un foglio di lavoro. documento, presentazione o modulo di cui dispongono dell'autorizzazione alla modifica. (La l'attivatore non viene eseguito quando si risponde a un modulo, ma solo quando viene aperto modificarla.) La lingua onOpen(e) è la più comunemente utilizzata per aggiungere elementi personalizzati voci di menu su Fogli, Presentazioni o Documenti Google oppure Moduli.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

L'attivatore onInstall(e) viene eseguito automaticamente quando un utente installa un Componente aggiuntivo Editor Documenti, Fogli, Presentazioni o Moduli Google. L'attivatore non viene eseguito quando un utente installa il componente aggiuntivo dal Google Workspace Marketplace sito web. Tieni presente che su ciò che può fare onInstall(e) sono previste alcune limitazioni, scopri di più su autorizzazione. L'utilizzo più comune di onInstall(e) è semplicemente chiamare onOpen(e) per aggiungere menu personalizzati. Dopotutto, quando si installa un componente aggiuntivo, il file è già aperto, quindi onOpen(e) non viene eseguito automaticamente a meno che il file non venga riaperto.

triggers/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

L'attivatore onEdit(e) viene eseguito automaticamente quando un utente modifica il valore di uno in un foglio di lavoro. La maggior parte dei onEdit(e) attivatori utilizza le informazioni nell'attributo oggetto evento affinché risponda in modo appropriato. Ad esempio, la funzione onEdit(e) riportata di seguito imposta un commento alla cella che registra l'ultima modifica.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

L'attivatore onSelectionChange(e) viene eseguito automaticamente quando un utente modifica l'elemento selezione in un foglio di lavoro. Per attivare questo trigger, devi aggiornare il un foglio di lavoro dopo aver aggiunto l'attivatore e ogni volta che viene aperto.

Se la selezione si sposta tra più celle in un breve lasso di tempo, una parte gli eventi di modifica potrebbero essere ignorati per ridurre la latenza. Ad esempio, se molti modelli le modifiche vengono apportate entro due secondi l'una dall'altra, solo la prima e l'ultima le modifiche alla selezione attiveranno l'attivatore onSelectionChange(e).

Nell'esempio riportato di seguito, se è selezionata una cella vuota, la funzione onSelectionChange(e) imposta il valore sfondo in rosso.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) e doPost(e)

L'attivatore doGet(e) viene eseguito automaticamente quando un utente visita un app web o un programma invia una richiesta GET HTTP a un'app web. doPost(e) viene eseguito quando un programma invia una richiesta POST HTTP a un dell'app web di Google. Questi fattori sono descritti più spesso nelle guide app web, servizio HTML, e Servizio di contenuti. Tieni presente che doGet(e) e doPost(e) non sono soggette alle limitazioni elencate sopra.

Tipi di trigger disponibili

Se le limitazioni sugli attivatori semplici impediscono di soddisfare dalle tue esigenze, un trigger installabile potrebbe funzionare. La tabella riportata di seguito riassume i tipi di trigger disponibili per ogni tipo di evento. Ad esempio, Fogli, Presentazioni, Moduli Google e Documenti supportano tutti i semplici attivatori di apertura, ma solo Fogli, Documenti e Moduli supportano trigger aperti installabili.

Evento Trigger semplici Trigger installabili
Apri
Fogli
Presentazioni
Moduli*
Documenti

function onOpen(e)
Fogli
Moduli*
Documenti
Modifica
Fogli

function onEdit(e)
Fogli
Modifica selezione
Fogli

function onSelectionChange(e)
Installa
Fogli
Presentazioni
Moduli
Documenti

function onInstall(e)
Cambia
Fogli
Invio modulo
Fogli
Moduli
A tempo (orologio)
Fogli
Presentazioni
Moduli
Documenti
Autonomi
Get
Autonomi

function doGet(e)
Pubblica
Autonomi

function doPost(e)

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