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. I trigger installabili offrono più funzionalità dei semplici trigger, ma devono essere attivati prima dell'uso. Per entrambi i tipi di trigger, Apps Script passa alla funzione attivata un oggetto evento contenente informazioni sul contesto in cui si è verificato l'evento.

Per iniziare

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

  • onOpen(e) viene eseguito quando un utente apre un foglio di lavoro, un documento, una presentazione o un modulo che l'utente è autorizzato a modificare.
  • onInstall(e) viene eseguito quando un utente installa un componente aggiuntivo di Editor da 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 in alto è un oggetto evento che viene passato alla funzione. L'oggetto contiene informazioni sul contesto che ha attivato l'attivatore, ma il suo utilizzo è facoltativo.

Restrizioni

Poiché i semplici trigger si attivano automaticamente senza chiedere l'autorizzazione all'utente, sono soggetti a diverse limitazioni:

  • Lo script deve essere legato a un file di Fogli, Presentazioni, Documenti o Moduli Google oppure essere un componente aggiuntivo che estende una di 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, chiamare Range.setValue() per modificare una cella non causa l'esecuzione dell'attivatore onEdit del foglio di lavoro.
  • Non possono accedere ai servizi che richiedono l'autorizzazione. Ad esempio, un attivatore semplice non può inviare un'email perché il servizio Gmail richiede l'autorizzazione, ma un attivatore semplice può tradurre una frase con il servizio Lingua, che è anonimo.
  • Possono modificare il file a cui sono associati, ma non possono accedere ad altri file perché ciò richiederebbe l'autorizzazione.
  • Potrebbero essere o meno in grado di determinare l'identità dell'utente corrente, a seconda di un insieme complesso di limitazioni di sicurezza.
  • Non possono essere pubblicati per più di 30 secondi.
  • In determinate circostanze, i componenti aggiuntivi Editor eseguono i trigger semplici onOpen(e) e onEdit(e) in una modalità senza autorizzazione che presenta alcune complicazioni aggiuntive. Per ulteriori informazioni, consulta la guida al ciclo di vita dell'autorizzazione dei componenti aggiuntivi.
  • I trigger semplici sono soggetti ai limiti di quota dei trigger di Apps Script.

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, un documento, una presentazione o un modulo che è autorizzato a modificare. (L'attivatore non viene eseguito quando si risponde a un modulo, ma solo quando viene aperto il modulo per modificarlo.) onOpen(e) viene utilizzato principalmente per aggiungere voci di menu personalizzate a Fogli, Presentazioni, Documenti o Moduli Google.

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 da Documenti, Fogli, Presentazioni o Moduli Google. L'attivatore non viene eseguito quando un utente installa il componente aggiuntivo dal sito web di Google Workspace Marketplace. Tieni presente che esistono alcune limitazioni relative a ciò che onInstall(e) può fare. Scopri di più sull'autorizzazione. L'utilizzo più comune di onInstall(e) è semplicemente richiamare onOpen(e) per aggiungere menu personalizzati. Dopotutto, quando viene installato un componente aggiuntivo, il file è già aperto, quindi onOpen(e) non viene eseguito automaticamente a meno che 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 una cella in un foglio di lavoro. La maggior parte dei trigger di onEdit(e) utilizza le informazioni nell'oggetto evento per rispondere in modo appropriato. Ad esempio, la funzione onEdit(e) riportata di seguito imposta un commento alla cella che registra l'ultima volta che è stata modificata.

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 la selezione in un foglio di lavoro. Per attivare questo attivatore, devi aggiornare il foglio di lavoro una volta aggiunto l'attivatore e ogni volta che viene aperto.

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

Nell'esempio seguente, se viene selezionata una cella vuota, la funzione onSelectionChange(e) imposta lo sfondo della cella 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'app web. Questi attivatori sono descritti più in dettaglio nelle guide alle app web, al servizio HTML e al servizio di contenuti. Tieni presente che doGet(e) e doPost(e) non sono soggetti alle limitazioni elencate sopra.

Tipi di trigger disponibili

Se le limitazioni sui trigger semplici impediscono di soddisfare le tue esigenze, potrebbe funzionare un trigger installabile. La tabella riportata di seguito riassume i tipi di trigger disponibili per ogni tipo di evento. Ad esempio, Fogli, Presentazioni, Moduli e Documenti Google supportano tutti i semplici attivatori di apertura, ma solo Fogli, Documenti e Moduli supportano gli attivatori 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)
Cambio
Fogli
Invio modulo
Fogli
Moduli
A tempo (orologio)
Fogli
Presentazioni
Moduli
Documenti
Autonomo
Get
Autonomo

function doGet(e)
Post
Autonomo

function doPost(e)

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