Les déclencheurs Apps Script provoquent un script spécifié. (la fonction du déclencheur) à exécuter chaque fois qu'un événement spécifié se produit. Seuls certains événements peuvent déclencher des déclencheurs, et chaque L'application Google Workspace est compatible avec un autre ensemble d'événements.
Lorsqu'un déclencheur est exécuté, un objet événement est créé. Cette structure JSON contient des détails sur l'événement qui s'est produit. Les informations contenues dans l'événement la structure d'un objet est organisée différemment en fonction du type de déclencheur.
Une fois l'objet événement créé, Apps Script le transmet en tant que paramètre à la méthode
la fonction de déclenchement. La fonction de déclenchement est une fonction de rappel que vous devez
vous mettre en œuvre, de prendre les mesures appropriées pour répondre
. Par exemple, dans un module complémentaire d'éditeur, un déclencheur
permet de créer des éléments de menu complémentaires lorsqu'un document est ouvert. Dans ce cas, vous
implémenter sur la fonction de déclencheur onOpen(e)
pour créer les éléments de menu que le module complémentaire
en utilisant, par exemple,
les données de l'objet d'événement.
Vous trouverez sur cette page des consignes sur l'utilisation de déclencheurs éditeur des projets complémentaires.
Types de déclencheurs du module complémentaire d'éditeur
Vous pouvez utiliser la plupart des types de déclencheurs génériques disponibles pour les projets Apps Script. dans les modules complémentaires de l'éditeur, y compris les déclencheurs simples et la plupart des déclencheurs installables. La l'ensemble exact de types de déclencheurs disponibles dépend de l'application étendue.
Le tableau suivant présente les types de déclencheurs simples et installables qui Les modules complémentaires des éditeurs peuvent utiliser et fournissent des liens vers les objets d'événement correspondants:
Événement | Objet événement | Déclencheurs simples | Déclencheurs installables |
---|---|---|---|
Ouvrir Un fichier d'éditeur est ouvert. |
<ph type="x-smartling-placeholder"></ph>
Objet d'événement Docs onOpen <ph type="x-smartling-placeholder"></ph> Objet d'événement Forms onOpen Objet d'événement Sheets onOpen . Objet d'événement Slides onOpen |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Installer Le module complémentaire est installé. |
<ph type="x-smartling-placeholder"></ph> Objet d'événement onInstall |
![]() ![]() ![]() ![]()
|
|
Modifier Le contenu des cellules de la feuille de calcul a été modifié. |
<ph type="x-smartling-placeholder"></ph> Objet d'événement Sheets onEdit |
![]()
|
![]() |
Modifier Le contenu d'une feuille est modifié ou mis en forme. |
<ph type="x-smartling-placeholder"></ph> Objet d'événement Sheets onChange |
![]() |
|
Envoi du formulaire Un formulaire Google Forms est envoyé. |
<ph type="x-smartling-placeholder"></ph>
Objet d'événement d'envoi de formulaire Forms <ph type="x-smartling-placeholder"></ph> Objet d'événement d'envoi de formulaire Sheets |
![]() ![]() |
|
En fonction du temps (horloge) Le déclencheur s'exécute à un moment précis ou à un intervalle spécifique. |
<ph type="x-smartling-placeholder"></ph> Objet d'événement basé sur l'heure |
![]() ![]() ![]() ![]() |
* L'événement d'ouverture de Google Forms ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour répondre, mais plutôt lorsqu'un éditeur ouvre le formulaire pour le modifier.
Déclencheurs simples dans les modules complémentaires
Les déclencheurs simples utilisent un ensemble ne peuvent pas utiliser de services nécessitant une autorisation automatiquement activé. Dans certains cas, un simple événement déclencheur être géré par un déclencheur installable à la place.
Vous pouvez ajouter un déclencheur simple à un module complémentaire en implémentant simplement une fonction par l'un des noms réservés suivants:
onOpen(e)
s'exécute lorsqu'un utilisateur ouvre un document, une feuille de calcul ou présentation.onOpen(e)
peut également s'exécuter lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lorsque vous répondez au formulaire). Elle ne s'exécute que si l'utilisateur a l'autorisation de modifier le fichier en question et sert le plus souvent à créer éléments du menu.onInstall(e)
s'exécute lorsqu'un utilisateur installe un module complémentaire. Prix habituel :onInstall(e)
est simplement utilisé pour appeleronOpen(e)
. Cela garantit que les menus des modules complémentaires s'affichent immédiatement après l'installation, sans que l'utilisateur ait besoin d'actualiser la page.onEdit(e)
s'exécute lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne s'active pas en réponse aux déplacements de cellules, à la mise en forme ou d'autres modifications qui n'affectent pas les valeurs des cellules.
Restrictions
Les déclencheurs simples des modules complémentaires sont soumis au même restrictions qui régissent les dans d'autres types de projets Apps Script. Notez en particulier ces lors de la conception de modules complémentaires:
- Les déclencheurs simples ne s'exécutent pas si un fichier est ouvert en lecture seule commentaire). Cela empêche le remplissage des menus de vos modules complémentaires.
- Dans certains cas, les modules complémentaires des éditeurs exécutent leur
onOpen(e)
et Déclencheurs simplesonEdit(e)
en mode sans autorisation. Ce mode présente d'autres complications, comme indiqué dans le modèle d'autorisation complémentaire. - Les déclencheurs simples ne peuvent pas utiliser les services ni prendre d'autres actions qui nécessitent autorisation, sauf si décrits dans le modèle d'autorisation complémentaire.
- Les déclencheurs simples ne peuvent pas s'exécuter pendant plus de 30 secondes. Veillez à réduire au maximum la quantité de traitement effectuée par une fonction de déclencheur simple.
- Les déclencheurs simples sont soumis aux déclencheurs Apps Script limites de quota.
Déclencheurs installables dans les modules complémentaires
Les modules complémentaires peuvent
de créer et modifier de façon automatisée des déclencheurs installables
avec le service Apps Script Script
. module complémentaire
Les déclencheurs installables ne peuvent pas être créés manuellement. Contrairement aux déclencheurs simples,
les déclencheurs installables peuvent utiliser
des services qui nécessitent une autorisation.
Les déclencheurs à installer dans les modules complémentaires n'envoient pas d'e-mails d'erreur à l'utilisateur lorsqu'il rencontre des erreurs, car dans la plupart des cas, l'utilisateur pour résoudre le problème. C'est pourquoi vous devez concevoir votre module complémentaire gérer efficacement les erreurs pour le compte de l'utilisateur dans la mesure du possible.
Les modules complémentaires peuvent utiliser les déclencheurs installables suivants:
- Les déclencheurs installables de type Ouvrir s'exécutent lorsqu'un utilisateur ouvre un document. feuille de calcul ou lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lorsque vous répondez au formulaire).
- Modifier : les déclencheurs installables s'exécutent lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne s'active pas en réponse à une mise en forme ou à des modifications qui n'affectent pas les valeurs des cellules.
- Les déclencheurs installables de modification s'exécutent lorsqu'un utilisateur apporte une modification feuille de calcul, y compris les modifications de mise en forme et de la feuille de calcul (par exemple, l'ajout d'une ligne).
Les déclencheurs installables Form-submit s'exécutent lorsqu'une réponse Google Forms est envoyé.
Déclencheurs temporels (également appelés déclencheurs d'horloge) se déclenchent à une heure précise ou de façon répétée un intervalle de temps régulier.
Autoriser les déclencheurs installables
Normalement, si un développeur met à jour un module complémentaire pour utiliser de nouveaux services qui nécessitent autorisation supplémentaire, les utilisateurs sont invités à autoriser à nouveau le module complémentaire chaque fois qu'ils l'utilisent.
Toutefois, les modules complémentaires qui utilisent des déclencheurs rencontrent des problèmes d'autorisation spéciaux. Imaginez un module complémentaire qui utilise un déclencheur pour surveiller les envois de formulaire : créateur peut autoriser le module complémentaire la première fois qu'il l'utilise, puis le laisser pendant des mois ou des années sans jamais rouvrir le formulaire. Si le développeur du module complémentaire devait le mettre à jour pour utiliser les nouveaux services qui nécessitant une autorisation supplémentaire, le créateur du formulaire ne verrait jamais car ils n'ont jamais rouvert le formulaire, et le module complémentaire cessent de fonctionner.
Contrairement aux déclencheurs des projets Apps Script standards, les déclencheurs
les modules complémentaires continuent de se déclencher même s'ils nécessitent une nouvelle autorisation. Toutefois, le script
échoue toujours s'il rencontre une ligne de code nécessitant une autorisation pour le script
n'a pas. Pour éviter cette situation, les développeurs peuvent utiliser la méthode
ScriptApp.getAuthorizationInfo()
pour contrôler l'accès aux parties de code qui ont changé entre les versions publiées de
le module complémentaire.
Vous trouverez ci-dessous un exemple de structure recommandée dans les fonctions de déclenchement afin de éviter les pièges liés aux autorisations. L'exemple de fonction de déclencheur répond à une d'envoi de formulaire dans un module complémentaire Google Sheets et, si une nouvelle autorisation obligatoire, envoie à l'utilisateur du module complémentaire un e-mail d'alerte au format HTML.
Code.gs
authorizationemail.html
Restrictions
Les déclencheurs installables dans les modules complémentaires sont soumis aux mêmes restrictions qui régissent les déclencheurs installables dans d'autres types de projets Apps Script.
En plus de ces restrictions, plusieurs restrictions s'appliquent aux éléments installables dans les modules complémentaires en particulier:
- Chaque module complémentaire ne peut avoir qu'un seul déclencheur de chaque type, par utilisateur et par document. Par exemple, dans une feuille de calcul, un utilisateur donné ne peut effectuer qu'une seule modification de formulaire, même si l'utilisateur peut également avoir un déclencheur d'envoi de formulaire ou un déclencheur temporel dans la même feuille de calcul. Un autre utilisateur disposant d'un accès à la même feuille de calcul peuvent avoir leur propre ensemble distinct de déclencheurs.
- Les modules complémentaires ne peuvent créer des déclencheurs que pour le fichier dans lequel ils sont utilisés. Autrement dit, un module complémentaire utilisé dans le document A ne peut pas créer de déclencheur pour surveiller quand le document Google Docs B est ouvert.
- Les déclencheurs basés sur l'heure ne peuvent pas s'exécuter plus d'une fois par heure.
- Les modules complémentaires n'envoient pas automatiquement un e-mail à l'utilisateur lorsque du code est exécuté par le déclencheur installable génère une exception. Il appartient au développeur de vérifier en cas d'échec et de les gérer de façon optimale.
- Les déclencheurs du module complémentaire s'arrêtent dans les situations suivantes:
<ph type="x-smartling-placeholder">
- </ph>
- Si le module complémentaire est désinstallé par l'utilisateur,
- Si le module complémentaire est désactivé dans un document (s'il est réactivé, le déclencheur est de nouveau opérationnel) ;
- Si le développeur annule la publication du module complémentaire ou envoie une version non fonctionnelle au dans une boutique en ligne.
- Les fonctions de déclenchement des modules complémentaires s'exécutent jusqu'à ce qu'elles atteignent du code utilisant un service non autorisé, auquel ils s’arrêtent. Cela n'est vrai que si le module complémentaire est publié ; le même déclencheur dans un projet Apps Script classique ou un module complémentaire non publié ne s'exécutent pas du tout si une partie du script une autorisation.
- Les déclencheurs installables sont soumis aux déclencheurs Apps Script limites de quota.