Déclencheurs des modules complémentaires Editor

Les déclencheurs Apps Script entraînent l'exécution d'une fonction de script spécifiée (la fonction de déclencheur) 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 accepte un ensemble d'événements différent.

Lorsqu'un déclencheur est exécuté, un objet d'événement est créé. Cette structure JSON contient des détails sur l'événement qui s'est produit. Les informations de la structure de l'objet événement sont organisées 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 fonction de déclencheur. La fonction de déclenchement est une fonction de rappel que vous devez implémenter vous-même pour effectuer les actions appropriées pour répondre à l'événement. Par exemple, dans un module complémentaire de l'éditeur, un déclencheur est utilisé pour créer des éléments de menu complémentaire lorsqu'un document est ouvert. Dans ce cas, implémentez la fonction de déclencheur 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 événement.

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

Types de déclencheurs du module complémentaire de l'é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 des éditeurs, y compris les déclencheurs simples et la plupart des déclencheurs installables. L'ensemble exact des types de déclencheurs disponibles dépend de l'application étendue.

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

Événement Objet événement Déclencheurs simples Déclencheurs installables
Ouvrir
Un fichier d'édition est ouvert.
Objet d'événement onOpen Docs
Objet d'événement onOpen Forms
Objet d'événement Sheets onOpen
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 des cellules de la feuille de calcul a été modifié.
Objet d'événement Sheets onEdit Sheets

function onEdit(e)

Sheets
Modification
Le contenu d'une feuille est modifié ou mis en forme.
Objet d'événement Sheets onChange Sheets
Envoi du formulaire
Un formulaire Google Forms est envoyé.
Objet d'événement d'envoi de formulaire Forms
Objet d'événement d'envoi de formulaire dans Sheets
Forms
Sheets
En fonction de l'heure (horloge)
Le déclencheur s'exécute à une heure ou à un intervalle spécifié.
Objet d'événement basé sur 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 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 de noms de fonctions réservés, ne peuvent pas utiliser de services nécessitant une autorisation et sont automatiquement activés. Dans certains cas, un simple événement déclencheur peut être géré par un déclencheur installable.

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

  • onOpen(e) s'exécute lorsqu'un utilisateur ouvre un document, une feuille de calcul ou une présentation. onOpen(e) peut également s'exécuter lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lors de la réponse au formulaire). Elle ne s'exécute que si l'utilisateur est autorisé à modifier le fichier en question. Elle est le plus souvent utilisée pour créer des éléments de menu.
  • onInstall(e) s'exécute lorsqu'un utilisateur installe un module complémentaire. En général, onInstall(e) sert simplement à appeler onOpen(e). Cela garantit que les menus 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 dans les modules complémentaires sont soumis aux mêmes restrictions que celles qui régissent les déclencheurs simples dans les autres types de projets Apps Script. Tenez compte en particulier de ces restrictions lorsque vous concevez des modules complémentaires:

  • Les déclencheurs simples ne s'exécutent pas si un fichier est ouvert en lecture seule (vue ou commentaire). Ce comportement empêche le remplissage des menus des modules complémentaires.
  • Dans certains cas, les modules complémentaires des éditeurs exécutent leurs déclencheurs simples onOpen(e) et onEdit(e) en mode sans autorisation. Ce mode présente des complications supplémentaires, 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 indication contraire dans le modèle d'autorisation complémentaire.
  • Les déclencheurs simples ne peuvent pas durer plus de 30 secondes. Veillez à minimiser la quantité de traitement effectuée dans une simple fonction de déclenchement.
  • Les déclencheurs simples sont soumis aux limites de quota des déclencheurs Apps Script.

Déclencheurs installables dans les modules complémentaires

Les modules complémentaires peuvent créer et modifier par programmation des déclencheurs installables avec le service Apps Script Script. En revanche, ils 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 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 ne peut pas résoudre le problème. C'est pourquoi vous devez concevoir votre module complémentaire de sorte qu'il gère correctement les erreurs au nom de l'utilisateur, dans la mesure du 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 ou une feuille de calcul, ou lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lorsqu'il répond au formulaire).
  • Les déclencheurs installables de type Modifier 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 à d'autres modifications qui n'affectent pas les valeurs des cellules.
  • Les déclencheurs installables Modification s'exécutent lorsqu'un utilisateur apporte une modification à une feuille de calcul, y compris des modifications de mise en forme et des modifications apportées à la feuille de calcul elle-même (par exemple, en ajoutant une ligne).
  • Les déclencheurs installables Form-submit s'exécutent lorsqu'une réponse Google Forms est envoyée.

  • Les déclencheurs basés sur le temps (également appelés déclencheurs d'horloge) se déclenchent à un moment précis ou de manière répétée sur un intervalle de temps régulier.

Autoriser des déclencheurs installables

Normalement, si un développeur met à jour un module complémentaire pour qu'il utilise de nouveaux services nécessitant une autorisation supplémentaire, les utilisateurs sont invités à autoriser à nouveau le module complémentaire la prochaine fois qu'ils l'utilisent.

Toutefois, les modules complémentaires qui utilisent des déclencheurs font face à des questions d'authentification spéciales. Imaginez un module complémentaire qui utilise un déclencheur pour surveiller les envois de formulaire: un créateur de formulaire peut autoriser le module la première fois qu'il l'utilise, puis le laisser fonctionner pendant des mois ou des années sans jamais rouvrir le formulaire. Si le développeur du module complémentaire mettait à jour le module complémentaire pour qu'il utilise 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'aura jamais rouvert le formulaire et le module complémentaire cesserait de fonctionner.

Contrairement aux déclencheurs des projets Apps Script standards, ceux des modules complémentaires continuent de se déclencher même s'ils nécessitent une nouvelle autorisation. Toutefois, le script échoue toujours s'il atteint une ligne de code qui nécessite une autorisation dont le script ne dispose pas. Pour éviter cette situation, les développeurs peuvent utiliser la méthode ScriptApp.getAuthorizationInfo() afin de contrôler l'accès à certaines parties du code qui ont changé entre les versions publiées du module complémentaire.

Vous trouverez ci-dessous un exemple de la structure recommandée à utiliser dans les fonctions de déclenchement afin d'éviter les pièges d'autorisation. L'exemple de fonction de déclencheur répond à un événement d'envoi de formulaire dans un module complémentaire Google Sheets et, si une nouvelle autorisation est requise, envoie à l'utilisateur du module complémentaire un e-mail d'alerte à l'aide d'un modèle de code HTML.

Code.gs

déclencheurs/form/Code.gs
/**
 * 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.
  }
}

e-mail_autorisation.html

déclencheurs/form/AuthorizationEmail.html
<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 dans les 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.

En plus de ces restrictions, plusieurs restrictions s'appliquent spécifiquement aux déclencheurs installables dans les modules complémentaires:

  • Chaque module complémentaire ne peut être associé 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, bien qu'il puisse également avoir un déclencheur d'envoi de formulaire ou un déclencheur temporel dans la même feuille de calcul. Un autre utilisateur ayant accès à la même feuille de calcul peut disposer de 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 Google Docs A ne peut pas créer de déclencheur pour surveiller l'ouverture du Google Docs B.
  • 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 le code exécuté par un déclencheur installable génère une exception. Il appartient au développeur de vérifier la présence d'échecs et de les gérer correctement.
  • 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
    • Le développeur annule la publication du module complémentaire ou en envoie une version défectueuse à la plate-forme de téléchargement dédiée.
  • Les fonctions de déclencheur des modules complémentaires s'exécutent jusqu'à ce qu'elles atteignent le code qui utilise un service non autorisé, puis elles s'arrêtent. Cela ne s'applique 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 quota des déclencheurs Apps Script.