Trigger semplici

I trigger consentono a Google Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento, ad esempio 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à rispetto ai trigger semplici, ma devono essere attivati prima dell'uso. Per entrambi i tipi di trigger, Apps Script passa alla funzione attivata un oggetto evento che contiene informazioni sul contesto in cui si è verificato l'evento.

Per informazioni su come utilizzare i trigger nei progetti di componenti aggiuntivi di Google Workspace, consulta Trigger per i componenti aggiuntivi di Google Workspace.

Per iniziare

Per utilizzare un trigger semplice, crea una funzione che utilizzi uno di questi nomi di funzioni riservate:

• onOpen(e) viene eseguita quando un utente apre un foglio di lavoro, un documento, una presentazione o un modulo che ha l'autorizzazione a modificare.
• onInstall(e) viene eseguita quando un utente installa un componente aggiuntivo dell'editor da Documenti, Fogli, Presentazioni o Moduli Google.
• onEdit(e) viene eseguita quando un utente modifica un valore in un foglio di lavoro.
• onSelectionChange(e) viene eseguita quando un utente modifica la selezione in un foglio di lavoro.
• doGet(e) viene eseguita quando un utente visita un'app web o un programma invia una richiesta HTTP GET a un'app web.
• doPost(e) viene eseguita quando un programma invia una richiesta HTTP POST a un'app web.

Il parametro e nei nomi delle funzioni sopra riportati è un oggetto evento passato alla funzione. L'oggetto contiene informazioni sul contesto che ha causato l'attivazione del trigger, ma il suo utilizzo è facoltativo.

Restrizioni

Poiché i trigger semplici vengono attivati automaticamente, senza chiedere l'autorizzazione all'utente, sono soggetti a diverse restrizioni:

• Lo script deve essere associato 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 di script e le richieste API non causano l'esecuzione dei trigger. Ad esempio, la chiamata di Range.setValue() per modificare una cella non causa l'esecuzione del trigger onEdit del foglio di lavoro.
• Non possono accedere ai servizi che richiedono l' autorizzazione. Ad esempio, un trigger semplice non può inviare un'email perché il servizio Gmail richiede l'autorizzazione, ma un trigger semplice può tradurre una frase con il servizio Language, che è anonimo.
• Possono modificare il file a cui sono associati, ma non possono accedere ad altri file perché ciò richiederebbe l'autorizzazione.
• Potrebbero essere in grado o meno di determinare l'identità dell'utente attuale, a seconda di un insieme complesso di restrizioni di sicurezza.
• Non possono essere eseguiti per più di 30 secondi.
• In determinate circostanze, i componenti aggiuntivi dell'editor eseguono i trigger semplici onOpen(e) e onEdit(e) in modalità senza autorizzazione, il che comporta alcune complicazioni aggiuntive. Per saperne di più, 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 quota limits.

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

onOpen(e)

Il trigger onOpen(e) viene eseguito automaticamente quando un utente apre un foglio di lavoro, un documento, una presentazione o un modulo che ha l'autorizzazione a modificare. (Il trigger non viene eseguito quando si risponde a un modulo, ma solo quando si apre il modulo per modificarlo.) onOpen(e) viene utilizzato più comunemente per aggiungere voci di menu personalizzate a Fogli, Presentazioni, Documenti o Moduli Google.

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

Il trigger onInstall(e) viene eseguito automaticamente quando un utente installa un componente aggiuntivo dell'editor da Documenti, Fogli, Presentazioni o Moduli Google. Il trigger non viene eseguito quando un utente installa il componente aggiuntivo dal sito web di Google Workspace Marketplace. L'utilizzo più comune di onInstall(e) è chiamare onOpen(e) per aggiungere menu personalizzati. Dopo l'installazione di un componente aggiuntivo, il file è già aperto, quindi onOpen(e) non viene eseguito autonomamente a meno che il file non venga riaperto. Tieni presente che esistono alcune restrizioni su ciò che onInstall(e) può fare. Scopri di più su autorizzazione.

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

Il trigger onEdit(e) viene eseguito automaticamente quando un utente modifica il valore di una cella in un foglio di lavoro. La maggior parte dei onEdit(e) trigger utilizza le informazioni nell' oggetto evento per rispondere in modo appropriato. Ad esempio, la funzione onEdit(e) riportata di seguito imposta un commento sulla cella che registra l'ultima volta che è stata modificata.

/**
 * 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()}`);
}

Il trigger onEdit() mette in coda solo fino a 2 eventi trigger.

onSelectionChange(e)

Il trigger onSelectionChange(e) viene eseguito automaticamente quando un utente modifica la selezione in un foglio di lavoro. Per attivare questo trigger, aggiorna il foglio di lavoro una volta aggiunto il trigger e ogni volta che viene aperto.

Se la selezione si sposta tra più celle in un breve periodo 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 della selezione attivano il trigger onSelectionChange(e).

Nell'esempio seguente, se viene selezionata una cella vuota, la funzione onSelectionChange(e) imposta lo sfondo della cella su rosso.

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

Il trigger doGet(e) viene eseguito automaticamente quando un utente visita un' app web o un programma invia una richiesta HTTP GET a un'app web. doPost(e) viene eseguito quando un programma invia una richiesta HTTP POST a un' app web. Questi trigger sono illustrati più dettagliatamente nelle guide alle app web, al servizio HTML, e al servizio Content. Tieni presente che doGet(e) e doPost(e) non sono soggetti alle restrizioni sopra elencate.

Tipi di trigger disponibili

Se le restrizioni sui trigger semplici impediscono loro di soddisfare le tue esigenze, potrebbe essere utile un trigger installabile invece. 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 trigger di apertura semplici, ma solo Fogli, Documenti e Moduli supportano i trigger di apertura installabili.

Evento	Trigger semplici	Trigger installabili
Apri	function onOpen(e)
Modifica	function onEdit(e)
Modifica della selezione	function onSelectionChange(e)
Installa	function onInstall(e)
Cambia
Invio del modulo
Basato sul tempo (orologio)
Aumenta	function doGet(e)
Pubblica	function doPost(e)

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