Déclencheurs simples

Les déclencheurs permettent à Apps Script d'exécuter une fonction automatiquement lorsqu'un certain événement, comme l'ouverture d'un document, se produit. Les déclencheurs simples sont un ensemble des fonctions réservées intégrées dans 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 que les simples déclencheurs, mais qui doivent être activées avant utilisation. Pour les deux de déclencheurs, Apps Script transmet la fonction déclenchée Un objet é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 utilisant l'un de ces Noms de fonctions réservés:

• onOpen(e) s'exécute lorsqu'un utilisateur ouvre une feuille de calcul, un document, une présentation ou que l'utilisateur est autorisé à modifier.
• onInstall(e) s'exécute lorsqu'un utilisateur installe une Module complémentaire de l'éditeur depuis 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 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.

Le paramètre e dans les noms de fonction ci-dessus est un objet d'événement transmis à . L'objet contient des informations sur le contexte à l'origine de l'événement se déclenche, mais son utilisation est facultative.

Restrictions

Parce que les déclencheurs simples se déclenchent automatiquement, sans demander à l'utilisateur une autorisation, ils sont soumis à plusieurs restrictions:

• Le script doit être lié à un compte Google un fichier Sheets, Slides, Docs ou Forms, ou être un module complémentaire qui étend l'un des ces applications.
• Elles ne s'exécutent pas si un fichier est ouvert en mode lecture seule (lecture ou commentaire).
• Les exécutions de scripts et les requêtes API n'entraînent pas l'exécution de déclencheurs. Par exemple, appel de Range.setValue() en cours pour modifier une cellule n'entraîne pas l'exécution du déclencheur onEdit de la feuille de calcul.
• Ils ne peuvent pas accéder aux services qui nécessitent autorisation. Par exemple, un déclencheur simple ne peut pas envoyer d'e-mail, car Le service Gmail nécessite une autorisation, mais un déclencheur simple peut traduire une expression Service de langue, qui est anonyme.
• Ils peuvent modifier le fichier auquel ils sont liés, mais ne peuvent pas accéder aux 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 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 onOpen(e) et onEdit(e) déclencheurs simples dans un mode sans autorisation qui présente quelques complications supplémentaires. Pour en savoir plus, consultez les ce guide sur le cycle de vie des autorisations des modules complémentaires.
• Les déclencheurs simples sont soumis aux déclencheurs Apps Script limites de quota.

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. document, présentation ou formulaire qu'il est autorisé à modifier. (Le ne s'exécute pas lors de la réponse à un formulaire, mais seulement à l'ouverture du formulaire la modifier.) Le plus souvent, on utilise onOpen(e) pour ajouter des éléments de menu vers Google Sheets, Slides, Docs ou Formulaires.

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

Le déclencheur onInstall(e) s'exécute automatiquement lorsqu'un utilisateur installe une Module complémentaire de l'éditeur depuis Google Docs, Sheets, Slides ou Forms. Le déclencheur ne s'exécute pas lorsqu'un utilisateur installe le module complémentaire à partir de Google Workspace Marketplace sur votre site Web. Notez que onInstall(e) peut faire l'objet de certaines restrictions. En savoir plus sur autorisation. L'utilisation la plus courante de onInstall(e) consiste simplement à appeler onOpen(e) pour ajouter personnalisés. Après tout, lorsqu’un module complémentaire est installé, le fichier est déjà ouvert, Ainsi, onOpen(e) ne s'exécute pas seul, sauf si le fichier est rouvert.

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

Le déclencheur onEdit(e) s'exécute automatiquement lorsqu'un utilisateur modifie la valeur d'une cellule d'une feuille de calcul. La plupart des déclencheurs onEdit(e) utilisent les informations du objet event 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 fois qu'il a été modifié.

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

Le déclencheur onSelectionChange(e) s'exécute automatiquement lorsqu'un utilisateur modifie le dans une feuille de calcul. Pour activer ce déclencheur, vous devez actualiser la feuille de calcul une fois que le déclencheur est ajouté et chaque fois que la feuille de calcul est ouverte.

Si la sélection se déplace entre plusieurs cellules en peu de temps, une partie les événements de modification peuvent être ignorés pour réduire la latence. Par exemple, si plusieurs sélections les modifications sont effectuées à moins de deux secondes l'une de l'autre, seules la première et la dernière modifications de la 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 sa valeur l'arrière-plan en rouge.

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) et doPost(e)

Le déclencheur doGet(e) s'exécute automatiquement lorsqu'un utilisateur consulte un Une application Web ou 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 à un de votre application Web. Ces déclencheurs sont présentés plus en détail dans les guides applications Web, service HTML, et Service de contenu. Notez que doGet(e) et Les doPost(e) ne sont pas soumis aux restrictions listées ci-dessus.

Types de déclencheurs disponibles

si les restrictions imposées aux déclencheurs simples les empêchent de respecter selon vos besoins, un déclencheur installable peut fonctionner à la place. 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 Tous les documents sont compatibles avec les déclencheurs ouverts simples, mais seuls Sheets, Docs et Forms sont compatibles. déclencheurs ouverts installables.

Événement	Déclencheurs simples	Déclencheurs installables
Ouvrir	function onOpen(e)
Modifier	function onEdit(e)
Modification de la sélection	function onSelectionChange(e)
Installer	function onInstall(e)
Modifier
Envoi de formulaire
En fonction du temps (horloge)
Télécharger	function doGet(e)
Publier	function doPost(e)

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