I trigger consentono ad Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento, come l'apertura di un documento. I semplici attivatori 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 semplici trigger, ma devono essere attivati prima dell'uso. Per entrambi i tipi di trigger, Apps Script trasmette 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 utilizza uno di questi nomi di funzioni riservati:
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 dell'editor dall'interno di 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 richiestaGET
HTTP a un'app web.doPost(e)
viene eseguito quando un programma invia una richiestaPOST
HTTP a un'app web.
Il parametro e
nei nomi delle funzioni sopra riportati è un oggetto evento che viene passato alla funzione. L'oggetto contiene informazioni sul contesto che ha causato l'attivazione dell'attivatore, ma il suo utilizzo è facoltativo.
Restrizioni
Poiché gli attivatori semplici si attivano automaticamente, senza chiedere all'utente l'autorizzazione, sono soggetti a diverse limitazioni:
- Lo script deve essere associato a un file di Fogli, Presentazioni, Documenti o Moduli Google oppure essere un componente aggiuntivo che estenda 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 a
Range.setValue()
per modificare una cella non comporta l'esecuzione dell'attivatoreonEdit
del foglio di lavoro. - Non possono accedere ai servizi che richiedono l'autorizzazione. Ad esempio, un semplice trigger non può inviare un'email perché il servizio Gmail richiede l'autorizzazione, ma un semplice trigger 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é questo richiederebbe l'autorizzazione.
- Potrebbe o meno essere in grado di determinare l'identità dell'utente corrente, a seconda di un insieme complesso di limitazioni di sicurezza.
- Non possono essere eseguiti per più di 30 secondi.
- In determinate circostanze, i componenti aggiuntivi di Editor eseguono i trigger semplici
onOpen(e)
eonEdit(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 per il quale è autorizzato a modificare. L'attivatore non viene eseguito quando rispondi a un modulo, ma solo quando lo apri per modificarlo. onOpen(e)
viene usato principalmente per aggiungere voci di menu personalizzate a Fogli, Presentazioni, Documenti o Moduli Google.
onInstall(e)
L'attivatore onInstall(e)
viene eseguito automaticamente quando un utente installa un componente aggiuntivo di Editor dall'interno di Documenti, Fogli, Presentazioni o Moduli Google. L'attivatore non verrà eseguito quando un utente installa il componente aggiuntivo dal sito web di Google Workspace Marketplace. Tieni presente che esistono alcune limitazioni su ciò che può fare onInstall(e)
. Scopri di più sull'autorizzazione.
L'uso più comune di onInstall(e)
è semplicemente la chiamata a onOpen(e)
per aggiungere
menu personalizzati. Infatti, quando un componente aggiuntivo è installato, il file è già aperto e quindi onOpen(e)
non viene eseguito da solo a meno che il file non venga riaperto.
onEdit(e)
L'attivatore onEdit(e)
viene eseguito automaticamente quando un utente modifica il valore di una cella di un foglio di lavoro. La maggior parte degli attivatori onEdit(e)
utilizza le informazioni nell'oggetto evento per rispondere in modo appropriato.
Ad esempio, la funzione onEdit(e)
di seguito imposta un commento nella cella che registra l'ultima volta che è stata modificata.
onSelectionChange(e)
L'attivatore onSelectionChange(e)
viene eseguito automaticamente quando un utente modifica la selezione in un foglio di lavoro. Per attivare questo trigger, devi aggiornare il foglio di lavoro dopo averlo aggiunto e a ogni apertura.
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
alle selezioni entro due secondi l'una dall'altra, solo la prima e l'ultima
modifica alla selezione attiverà l'attivatore onSelectionChange(e)
.
Nell'esempio seguente, se viene selezionata una cella vuota, la funzione onSelectionChange(e)
imposta lo sfondo della cella su rosso.
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 maggiormente 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 attivatori disponibili
Se le limitazioni relative ai trigger semplici impediscono loro di soddisfare le tue esigenze, potrebbe funzionare invece un attivatore installabile. La tabella riportata di seguito riassume i tipi di attivatori 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 attivatori aperti installabili.
Evento | Trigger semplici | Trigger installabili |
---|---|---|
Apri |
|
|
Modifica |
|
|
Modifica selezione |
|
|
Installa |
|
|
Cambio |
|
|
Invio modulo |
|
|
A tempo (orologio) |
|
|
Get |
|
|
Post |
|
* L'evento aperto per Moduli Google non si verifica quando un utente apre un modulo per rispondere, ma piuttosto quando un editor apre il modulo per modificarlo.