Déclencheurs pour les modules complémentaires d'éditeurs

Les déclencheurs Apps Script exécutent une fonction de script spécifiée (la fonction de déclenchement) chaque fois qu'un événement spécifié se produit. Seuls certains événements peuvent déclencher des déclencheurs, et chaque application Google Workspace est compatible avec un ensemble d'événements différent.

Lorsqu'un déclencheur se déclenche, un objet d'événement est créé. Cette structure JSON contient des informations sur l'événement qui s'est produit. Les informations de la structure de l'objet d'événement sont organisées différemment en fonction du type de déclencheur.

Une fois l'objet d'événement créé, Apps Script le transmet en tant que paramètre à la fonction de déclenchement. La fonction de déclenchement est une fonction de rappel que vous devez implémenter vous-même pour effectuer les actions appropriées en réponse à l'événement. Par exemple, dans un module complémentaire d'éditeur, un déclencheur est utilisé pour créer des éléments de menu de module complémentaire lorsqu'un document est ouvert. Dans ce cas, vous implémentez une fonction de déclenchement onOpen(e) pour créer les éléments de menu dont le module complémentaire a besoin, en utilisant éventuellement les données de l'objet d'événement.

Cette page fournit des consignes sur l'utilisation des déclencheurs dans les projets de modules complémentaires d'éditeur.

Types de déclencheurs de modules complémentaires d'éditeur

Vous pouvez utiliser la plupart des types de déclencheurs génériques disponibles pour les projets Google Apps Script dans les modules complémentaires d'éditeur, y compris les déclencheurs simples et la plupart des déclencheurs installables. L'ensemble exact de types de déclencheurs disponibles dépend de l'application étendue.

Contrairement aux modules complémentaires d'éditeur, les modules complémentaires Google Workspace ne peuvent pas utiliser de déclencheurs simples ou installables Apps Script génériques. Ils utilisent plutôt des déclencheurs conçus spécifiquement pour les modules complémentaires Google Workspace. Pour en savoir plus, consultez Déclencheurs de modules complémentaires Google Workspace.

Le tableau suivant présente les types de déclencheurs simples et installables que les modules complémentaires d'éditeur peuvent utiliser, et fournit des liens vers les objets d'événement correspondants :

Événement	Objet d'événement	Déclencheurs simples	Déclencheurs installables
Ouvrir Un fichier d'éditeur est ouvert.	Objet d'événement onOpen Docs Objet d'événement onOpen Forms Objet d'événement onOpen Sheets Objet d'événement onOpen Slides	Docs Forms* Sheets Slides function onOpen(e)	Docs Forms Sheets
Installer Le module complémentaire est installé.	Objet d'événement onInstall	Docs Forms Sheets Slides function onInstall(e)
Modifier Le contenu d'une cellule de feuille de calcul est modifié.	Objet d'événement onEdit Sheets	Sheets function onEdit(e)	Sheets
Modifier Le contenu d'une feuille est modifié ou mis en forme.	Objet d'événement onChange Sheets		Sheets
Envoyer un formulaire Un formulaire Google Forms est envoyé.	Objet d'événement form-submit Forms Objet d'événement form-submit Sheets		Forms Sheets
Déclenché par le temps (horloge) Le déclencheur se déclenche à une heure ou à un intervalle spécifié.	Objet d'événement déclenché par le temps	Docs Forms Sheets Slides

* 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.

Déclencheurs simples dans les modules complémentaires

Les déclencheurs simples utilisent un ensemble de noms de fonctions réservés, ne peuvent pas utiliser de services nécessitant une autorisation et sont automatiquement activés pour être utilisés. Dans certains cas, un événement de déclencheur simple peut être géré par un déclencheur installable à la place.

Vous pouvez ajouter un déclencheur simple à un module complémentaire en implémentant une fonction avec l'un des noms réservés suivants :

• onOpen s'exécute lorsqu'un utilisateur ouvre un document, une feuille de calcul ou une présentation. onOpen peut également s'exécuter lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lorsque vous y répondez). Il ne s'exécute que si l'utilisateur est autorisé à modifier le fichier en question et est le plus souvent utilisé pour créer des éléments de menu.
• onInstall s'exécute lorsqu'un utilisateur installe un module complémentaire. En règle générale, onInstall n'est utilisé que pour appeler onOpen. Cela garantit que les menus du module complémentaire s'affichent immédiatement après l'installation sans que l'utilisateur n'ait à actualiser la page.
• onEdit s'exécute lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne se déclenche pas en réponse aux déplacements de cellules, à la mise en forme ou à d'autres modifications qui n'altèrent pas les valeurs des cellules.

Restrictions

Les déclencheurs simples des modules complémentaires sont soumis aux mêmes restrictions que celles qui régissent les déclencheurs simples dans d'autres types de projets Apps Script. Tenez compte de ces restrictions lors de la conception de modules complémentaires :

• Les déclencheurs simples ne s'exécutent pas si un fichier est ouvert en mode lecture seule (affichage ou commentaire). Ce comportement empêche le remplissage des menus de votre module complémentaire.
• Dans certaines circonstances, les modules complémentaires d'éditeur exécutent leurs déclencheurs simples onOpen et onEdit en mode sans autorisation. Ce mode présente des complications, comme indiqué dans le modèle d'autorisation des modules complémentaires.
• Les déclencheurs simples ne peuvent pas utiliser de services ni effectuer d'autres actions nécessitant une autorisation, sauf comme indiqué dans le modèle d'autorisation des modules complémentaires.
• Les déclencheurs simples ne peuvent pas s'exécuter pendant plus de 30 secondes. Réduisez au minimum la quantité de traitement effectuée dans une fonction de déclencheur simple.
• Les déclencheurs simples sont soumis aux limites de quotas de déclencheurs Apps Script .

Déclencheurs installables dans les modules complémentaires

Les modules complémentaires peuvent créer et modifier des déclencheurs installables de manière programmatique à l'aide du service Script Apps Script. Les déclencheurs installables des modules complémentaires ne peuvent pas être créés manuellement. Contrairement aux déclencheurs simples, les déclencheurs installables peuvent utiliser des services nécessitant une autorisation.

Les déclencheurs installables des modules complémentaires n'envoient pas d'e-mails d'erreur à l'utilisateur lorsqu'ils rencontrent des erreurs, car dans la plupart des cas, un utilisateur ne peut pas résoudre le problème. Pour cette raison, vous devez concevoir votre module complémentaire de manière à gérer les erreurs de manière appropriée pour l'utilisateur chaque fois que cela est possible.

Les modules complémentaires peuvent utiliser les déclencheurs installables suivants :

• Les déclencheurs installables Ouvrir s'exécutent lorsqu'un utilisateur ouvre un document, une feuille de calcul ou un formulaire dans l'éditeur (mais pas lorsqu'il y répond).
• Les déclencheurs installables Modifier s'exécutent lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne se déclenche pas en réponse à la mise en forme ou à d'autres modifications qui n'altèrent pas les valeurs des cellules.
• Les déclencheurs installables Modifier s'exécutent lorsqu'un utilisateur apporte une modification à une feuille de calcul, y compris des modifications de mise en forme et des modifications de la feuille de calcul elle-même (par exemple, l'ajout d'une ligne).

• Les déclencheurs installables Envoyer un formulaire s'exécutent lorsqu'une réponse à un formulaire Google Forms est envoyée.

  Il existe deux versions de déclencheurs d'envoi de formulaire : une pour Sheets (où les réponses aux formulaires sont collectées) et une pour Google Forms. L' objet d'événement transmis à une fonction de déclencheur d'envoi de formulaire Sheets est plus simple et renvoie les valeurs de réponse dans des tableaux simples. L' objet d'événement transmis à une fonction de déclencheur d'envoi de formulaire Forms fournit plus d'informations, contenues dans un objet FormResponse.

• Les **déclencheurs déclenchés par le temps** (également appelés déclencheurs d'horloge) se déclenchent à une heure spécifique ou de manière répétée à intervalles réguliers.

Autoriser les déclencheurs installables

Normalement, si un développeur met à jour un module complémentaire pour utiliser de nouveaux services nécessitant une autorisation supplémentaire, les utilisateurs sont invités à réautoriser le module complémentaire lors de leur prochaine utilisation.

Toutefois, les modules complémentaires qui utilisent des déclencheurs rencontrent des problèmes d'autorisation spécifiques. Imaginez un module complémentaire qui utilise un déclencheur pour surveiller les envois de formulaires : un créateur de formulaire peut autoriser le module complémentaire lors de sa première utilisation, puis le laisser s'exécuter pendant des mois ou des années sans jamais rouvrir le formulaire. Si le développeur du module complémentaire met à jour le module complémentaire pour utiliser de nouveaux services nécessitant une autorisation supplémentaire, le créateur du formulaire ne verra jamais la boîte de dialogue de réautorisation, car il n'a jamais rouvert le formulaire, et le module complémentaire cessera de fonctionner.

Contrairement aux déclencheurs des projets Apps Script standards, les déclencheurs des modules complémentaires continuent de se déclencher même s'ils nécessitent une réautorisation. Toutefois, le script échoue toujours s'il atteint une ligne de code qui nécessite une autorisation dont il ne dispose pas. Pour éviter cela, utilisez ScriptApp.getAuthorizationInfo pour limiter l'accès aux parties du code qui ont changé entre les versions de le module complémentaire.

Les exemples suivants montrent la structure recommandée à utiliser dans les fonctions de déclencheur pour éviter les pièges d'autorisation. La fonction de déclencheur d'exemple répond à un événement d'envoi de formulaire dans un module complémentaire Google Sheets et, si une réautorisation est requise, envoie à l'utilisateur du module complémentaire un e-mail d'alerte à l'aide d'un code HTML basé sur un modèle.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = "My Add-on Title";
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (
    authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.REQUIRED
  ) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty("lastAuthEmailDate");
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile("AuthorizationEmail");
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(
          Session.getEffectiveUser().getEmail(),
          "Authorization Required",
          message.getContent(),
          {
            name: addonTitle,
            htmlBody: message.getContent(),
          },
        );
      }
      props.setProperty("lastAuthEmailDate", today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Restrictions

Les déclencheurs installables des modules complémentaires sont soumis aux mêmes restrictions que celles qui régissent les déclencheurs installables dans d'autres types de projets Apps Script.

Outre ces restrictions, plusieurs restrictions s'appliquent spécifiquement aux déclencheurs installables des modules complémentaires :

• 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 donnée, un utilisateur donné ne peut avoir qu'un seul déclencheur de modification, mais il peut également avoir un déclencheur d'envoi de formulaire ou un déclencheur déclenché par le temps dans la même feuille de calcul. Un autre utilisateur ayant accès à la même feuille de calcul peut avoir son propre ensemble 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 Google Docs A ne peut pas créer de déclencheur pour surveiller l'ouverture du document Google Docs B.
• Les déclencheurs déclenchés par le temps ne peuvent pas s'exécuter plus d'une fois par heure.
• Les modules complémentaires n'envoient pas automatiquement d'e-mail à l'utilisateur lorsqu'une exception est générée par le code exécuté par un déclencheur installable. Il appartient au développeur de vérifier et de gérer les cas d'échec de manière appropriée.
• Les déclencheurs de modules complémentaires cessent de se déclencher dans les situations suivantes :
  • 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 redevient opérationnel), ou
  • Si le développeur annule la publication du module complémentaire ou envoie une version défectueuse au magasin de modules complémentaires.
• Les fonctions de déclencheur de module complémentaire s'exécutent jusqu'à ce qu'elles atteignent un code qui utilise un service non autorisé, auquel cas elles 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 standard ou un module complémentaire non publié ne s'exécute pas du tout si une partie du script nécessite une autorisation.
• Les déclencheurs installables sont soumis aux limites de quotas de déclencheurs Apps Script .