Les déclencheurs permettent à Apps Script d'exécuter automatiquement une fonction lorsqu'un événement spécifique se produit, comme l'ouverture d'un document. Les déclencheurs simples sont un ensemble de fonctions réservées intégrées à Apps Script, comme la fonction onOpen(e)
, qui s'exécute lorsqu'un utilisateur ouvre un fichier Google Docs, Sheets, Slides ou Forms.
Les déclencheurs installables offrent plus de fonctionnalités que les déclencheurs simples, mais doivent être activés avant utilisation. Pour les deux types de déclencheurs, Apps Script transmet à la fonction déclenchée un objet d'événement contenant des informations sur le contexte dans lequel l'événement s'est produit.
Premiers pas
Pour utiliser un déclencheur simple, il vous suffit de créer une fonction qui utilise l'un des noms de fonction réservés suivants :
onOpen(e)
s'exécute lorsqu'un utilisateur ouvre une feuille de calcul, un document, une présentation ou un formulaire qu'il est autorisé à modifier.onInstall(e)
s'exécute lorsqu'un utilisateur installe un module complémentaire de l'éditeur dans Google Docs, Sheets, Slides ou Forms.onEdit(e)
s'exécute lorsqu'un utilisateur modifie une valeur dans une feuille de calcul.onSelectionChange(e)
s'exécute lorsqu'un utilisateur modifie la sélection dans une feuille de calcul.doGet(e)
s'exécute lorsqu'un utilisateur consulte une application Web ou qu'un programme envoie une requête HTTPGET
à une application Web.doPost(e)
s'exécute lorsqu'un programme envoie une requête HTTPPOST
à une application Web.
Le paramètre e
dans les noms de fonction ci-dessus est un objet d'événement qui est transmis à la fonction. L'objet contient des informations sur le contexte qui a déclenché le déclencheur, mais son utilisation est facultative.
Restrictions
Étant donné que les déclencheurs simples se déclenchent automatiquement, sans demander l'autorisation de l'utilisateur, ils sont soumis à plusieurs restrictions :
- Le script doit être lié à un fichier Google Sheets, Slides, Docs ou Forms, ou être un module complémentaire qui étend l'une de ces applications.
- Elles ne s'exécutent pas si un fichier est ouvert en mode lecture seule (affichage ou commentaire).
- Les exécutions de scripts et les requêtes API n'entraînent pas l'exécution de déclencheurs. Par exemple, l'appel de
Range.setValue()
pour modifier une cellule n'entraîne pas l'exécution du déclencheuronEdit
de la feuille de calcul. - Il ne peut pas accéder aux services qui nécessitent une autorisation. Par exemple, un déclencheur simple ne peut pas envoyer d'e-mail, car le service Gmail nécessite une autorisation. En revanche, un déclencheur simple peut traduire une expression avec le service Language, qui est anonyme.
- Ils peuvent modifier le fichier auquel ils sont liés, mais ne peuvent pas accéder à d'autres fichiers, car cela nécessiterait une autorisation.
- Ils peuvent ou non être en mesure de déterminer l'identité de l'utilisateur actuel, en fonction d'un ensemble complexe de restrictions de sécurité.
- Elles ne peuvent pas durer plus de 30 secondes.
- Dans certains cas, les modules complémentaires de l'éditeur exécutent leurs déclencheurs simples
onOpen(e)
etonEdit(e)
en mode sans autorisation, ce qui présente quelques complications supplémentaires. Pour en savoir plus, consultez le guide sur le cycle de vie de l'autorisation des modules complémentaires. - Les déclencheurs simples sont soumis aux limites de quota des déclencheurs Apps Script.
Ces restrictions ne s'appliquent pas à doGet(e)
ni à doPost(e)
.
onOpen(e)
Le déclencheur onOpen(e)
s'exécute automatiquement lorsqu'un utilisateur ouvre une feuille de calcul, un document, une présentation ou un formulaire qu'il est autorisé à modifier. (Le déclencheur ne s'exécute pas lorsque vous répondez à un formulaire, mais uniquement lorsque vous l'ouvrez pour le modifier.) onOpen(e)
est le plus souvent utilisé pour ajouter des éléments de menu personnalisés à Google Sheets, Slides, Docs ou Forms.
onInstall(e)
Le déclencheur onInstall(e)
s'exécute automatiquement lorsqu'un utilisateur installe un module complémentaire de l'éditeur dans Google Docs, Sheets, Slides ou Forms. Le déclencheur ne s'exécute pas lorsqu'un utilisateur installe le module complémentaire à partir du site Web Google Workspace Marketplace. Notez que certaines restrictions s'appliquent à ce que onInstall(e)
peut faire. Pour en savoir plus, consultez Autorisation.
L'utilisation la plus courante de onInstall(e)
consiste simplement à appeler onOpen(e)
pour ajouter des menus personnalisés. En effet, lorsqu'un module complémentaire est installé, le fichier est déjà ouvert. Par conséquent, onOpen(e)
ne s'exécute pas seul, sauf si le fichier est rouvert.
onEdit(e)
Le déclencheur onEdit(e)
s'exécute automatiquement lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. La plupart des déclencheurs onEdit(e)
utilisent les informations de l'objet d'événement pour répondre de manière appropriée.
Par exemple, la fonction onEdit(e)
ci-dessous définit un commentaire sur la cellule qui enregistre la dernière date de modification.
onSelectionChange(e)
Le déclencheur onSelectionChange(e)
s'exécute automatiquement lorsqu'un utilisateur modifie la sélection dans une feuille de calcul. Pour activer ce déclencheur, vous devez actualiser la feuille de calcul une fois le déclencheur ajouté et chaque fois que vous ouvrez la feuille de calcul.
Si la sélection se déplace entre plusieurs cellules en peu de temps, certains événements de modification de la sélection peuvent être ignorés pour réduire la latence. Par exemple, si de nombreux changements de sélection sont effectués à moins de deux secondes d'intervalle, seuls le premier et le dernier changement de sélection activeront le déclencheur onSelectionChange(e)
.
Dans l'exemple ci-dessous, si une cellule vide est sélectionnée, la fonction onSelectionChange(e)
définit l'arrière-plan de la cellule sur rouge.
doGet(e)
et doPost(e)
Le déclencheur doGet(e)
s'exécute automatiquement lorsqu'un utilisateur visite une application Web ou qu'un programme envoie une requête HTTP GET
à une application Web. doPost(e)
s'exécute lorsqu'un programme envoie une requête HTTP POST
à une application Web. Ces déclencheurs sont présentés plus en détail dans les guides sur les applications Web, le service HTML et le service Content. Notez que doGet(e)
et doPost(e)
ne sont pas soumis aux restrictions listées ci-dessus.
Types de déclencheurs disponibles
Si les restrictions sur les déclencheurs simples les empêchent de répondre à vos besoins, un déclencheur installable peut être une meilleure solution. Le tableau ci-dessous récapitule les types de déclencheurs disponibles pour chaque type d'événement. Par exemple, Google Sheets, Slides, Forms et Docs sont tous compatibles avec les déclencheurs d'ouverture simples, mais seuls Sheets, Docs et Forms sont compatibles avec les déclencheurs d'ouverture installables.
Événement | Déclencheurs simples | Déclencheurs installables |
---|---|---|
Ouvrir |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Modifier |
![]()
|
![]() |
Modification de la sélection |
![]()
|
|
Installer |
![]() ![]() ![]() ![]()
|
|
Modifier |
![]() |
|
Envoi de formulaire |
![]() ![]() |
|
Déclencheur horaire (horloge) |
![]() ![]() ![]() ![]() ![]() |
|
Télécharger |
![]()
|
|
Publier |
![]()
|
* L'événement d'ouverture de Google Forms ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour y répondre, mais lorsqu'un éditeur l'ouvre pour le modifier.