Déclencheurs des modules complémentaires des éditeurs

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 		Documentation
Formulaires*
Feuilles
Diapositives

function onOpen(e)

 Documentation
Formulaires
Feuilles
Installer
Le module complémentaire est installé.		 <ph type="x-smartling-placeholder"></ph> Objet d'événement onInstall Documentation
Formulaires
Feuilles
Diapositives

function onInstall(e)
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 Feuilles

function onEdit(e)

 Feuilles
Modifier
Le contenu d'une feuille est modifié ou mis en forme.		 <ph type="x-smartling-placeholder"></ph> Objet d'événement Sheets onChange Feuilles
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 		Formulaires
Feuilles
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 Documentation
Formulaires
Feuilles
Diapositives

* 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 appeler onOpen(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 simples onEdit(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 le temps de traitement effectué par une simple fonction de déclencheur.
  • 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 une 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 pour 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

triggers/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.
  }
}

authorizationemail.html

triggers/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 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 des déclencheurs dans les 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, 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 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 redevient opérationnelle), ou
    • 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.