I trigger consentono ad 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 iniziare
Per utilizzare un trigger semplice, crea 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 o un modulo che ha l'autorizzazione a modificare.onInstall(e)
viene eseguito quando un utente installa un componente aggiuntivo 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 HTTPGET
a un'app web.doPost(e)
viene eseguito quando un programma invia una richiesta HTTPPOST
a un'app web.
Il parametro e
nei nomi delle funzioni riportati sopra è 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 limitazioni:
- Lo script deve essere associato a un file Fogli, Presentazioni, Documenti o Moduli Google oppure deve 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 a
Range.setValue()
per modificare una cella non comporta l'esecuzione del triggeronEdit
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 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 corrente, a seconda di un complesso insieme di limitazioni di sicurezza.
- Non possono essere riprodotti per più di 30 secondi.
- In determinate circostanze,
i componenti aggiuntivi dell'editor eseguono i
onOpen(e)
e ionEdit(e)
trigger semplici in una modalità senza autorizzazione che presenta alcune complicazioni aggiuntive. Per maggiori 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)
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 lo si apre per
modificarlo.) onOpen(e)
viene utilizzato più comunemente per aggiungere voci di menu personalizzate a Fogli, Presentazioni, Documenti o Moduli Google.
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 Google Workspace Marketplace. Tieni presente che
esistono alcune limitazioni su ciò che onInstall(e)
può fare. Scopri di più sull'autorizzazione.
L'uso più comune di onInstall(e)
è semplicemente chiamare onOpen(e)
per aggiungere
menu personalizzati. Dopo tutto, quando un componente aggiuntivo viene installato, il file è già aperto,
e quindi onOpen(e)
non viene eseguito autonomamente a meno che il file non venga riaperto.
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 trigger 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 nella cella che
registra l'ultima volta che è stata modificata.
onSelectionChange(e)
Il trigger 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 una volta aggiunto il trigger e ogni volta che viene aperto il foglio di lavoro.
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 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
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 più nel 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 attivatori disponibili
Se le limitazioni dei trigger semplici impediscono loro di soddisfare le tue esigenze, potrebbe funzionare un trigger installabile. La tabella seguente riassume i tipi di trigger disponibili per ogni tipo di evento. Ad esempio, Fogli, Presentazioni, Moduli e Documenti Google supportano tutti i semplici trigger di apertura, ma solo Fogli, Documenti e Moduli supportano i trigger di apertura installabili.
Evento | Trigger semplici | Trigger installabili |
---|---|---|
Apri |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Modifica |
![]()
|
![]() |
Modifica della selezione |
![]()
|
|
Installa |
![]() ![]() ![]() ![]()
|
|
Cambia |
![]() |
|
Invio del modulo |
![]() ![]() |
|
Basato sul tempo (orologio) |
![]() ![]() ![]() ![]() ![]() |
|
Aumenta |
![]()
|
|
Pubblica |
![]()
|
* L'evento di apertura per Google Moduli non si verifica quando un utente apre un modulo per rispondere, ma quando un editor lo apre per modificarlo.