Déclencheurs simples

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les déclencheurs permettent à Apps Script d'exécuter automatiquement une fonction lorsqu'un événement spécifique se produit, tel que l'ouverture d'un document. Les déclencheurs simples sont un ensemble de fonctions réservées intégrées à 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 de fonctionnalités que les déclencheurs simples, mais doivent être activés avant utilisation. Pour les deux types 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, créez simplement une fonction qui utilise l'un des noms de fonction réservés suivants:

  • onOpen(e) s'exécute lorsqu'un utilisateur ouvre une feuille de calcul, un document, une présentation ou un formulaire qu'il est autorisé à modifier.
  • onInstall(e) s'exécute lorsqu'un utilisateur installe un module complémentaire Editor à partir de 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 visite une application Web ou lorsqu'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 fonctions ci-dessus est un objet d'événement qui est transmis à la fonction. L'objet contient des informations sur le contexte qui a activé le déclencheur, mais son utilisation est facultative.

Restrictions

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

  • Le script doit être lié à un fichier Google Sheets, Slides, Docs ou Forms, ou être un module complémentaire qui étend l'une de ces applications.
  • Elles ne s'exécutent pas si un fichier est ouvert en lecture seule (lecture ou commentaire).
  • Les exécutions de script et les requêtes API n'entraînent pas l'exécution de déclencheurs. Par exemple, l'appel de Range.setValue() 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 nécessitant une 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 avec le service de langue, qui est anonyme.
  • Il peut modifier le fichier auquel il est lié, mais ne peut pas accéder aux autres fichiers, car cela nécessite une autorisation.
  • Ils peuvent ou non être en mesure de déterminer l'identité de l'utilisateur actuel, en fonction d'un ensemble complexe de restrictions de sécurité.
  • Elles ne peuvent pas être diffusées pendant plus de 30 secondes.
  • Dans certains cas, les modules complémentaires de l'éditeur exécutent leurs déclencheurs simples onOpen(e) et onEdit(e) dans un mode sans autorisation qui présente des complications supplémentaires. Pour en savoir plus, consultez le guide sur le cycle de vie des autorisations des modules complémentaires.
  • Les déclencheurs simples sont soumis aux limites de quota d'Apps Script.

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, un document, une présentation ou un formulaire qu'il est autorisé à modifier. (Le déclencheur ne s'exécute pas lorsque vous répondez à un formulaire, mais seulement à l'ouverture du formulaire pour le modifier.) onOpen(e) est le plus souvent utilisé pour ajouter des éléments de menu personnalisés à Google Sheets, Slides, Docs ou Forms.

déclencheurs/déclencheurs.gs
/**
 * 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 un module complémentaire Editor à partir de Google Docs, Sheets, Slides ou Forms. Le déclencheur ne s'exécute pas lorsqu'un utilisateur installe le module complémentaire à partir du site Web Google Workspace Marketplace. Notez que certaines restrictions peuvent être appliquées à onInstall(e). En savoir plus sur les autorisations L'utilisation la plus courante de onInstall(e) consiste simplement à appeler onOpen(e) pour ajouter des menus personnalisés. Après tout, lorsqu'un module complémentaire est installé, le fichier est déjà ouvert et onOpen(e) n'est pas exécuté seul s'il n'est pas rouvert.

déclencheurs/déclencheurs.gs
/**
 * 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 dans une feuille de calcul. La plupart des déclencheurs onEdit(e) utilisent les informations de l'objet événement 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 modification.

déclencheurs/déclencheurs.gs
/**
 * 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 la sélection dans une feuille de calcul. Pour activer ce déclencheur, vous devez actualiser la feuille de calcul une fois le déclencheur ajouté et chaque fois que la feuille de calcul est ouverte.

Si la sélection passe d'une cellule à une autre dans un court laps de temps, certains événements de modification de sélection peuvent être ignorés afin de réduire la latence. Par exemple, si de nombreuses modifications de sélection sont effectuées dans un délai de deux secondes, seules les première et dernière modifications de 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 l'arrière-plan de la cellule sur rouge.

déclencheurs/déclencheurs.gs
/**
 * 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 visite une application Web ou lorsqu'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. Ces déclencheurs sont décrits en détail dans les guides sur les applications Web, le service HTML et le service de contenu. Notez que doGet(e) et doPost(e) ne sont pas soumis aux restrictions répertoriées ci-dessus.

Types de déclencheurs disponibles

Si les restrictions imposées aux déclencheurs simples les empêchent de répondre à 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 Docs sont tous compatibles avec les déclencheurs d'ouverture simples, mais seuls Sheets, Docs et Forms sont compatibles avec les déclencheurs ouverts installables.

Événement Déclencheurs simples Déclencheurs installables
Ouvrir
Sheets
Slides
Forms*
Docs

function onOpen(e)

Sheets
Forms*
Docs
Modifier
Sheets

function onEdit(e)

Sheets
Modification de la sélection
Sheets

function onSelectionChange(e)

Installer
Sheets
Slides
Forms
Docs

function onInstall(e)

Modifier
Sheets
Envoi de formulaire
Sheets
Forms
En fonction de l'heure
Sheets
Slides
Forms
Docs
Sites
Application autonome
Télécharger
Sites
Application autonome

function doGet(e)

Publier
Sites
Application autonome

function doPost(e)

* L'événement Google Forms ouvert ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour répondre, mais lorsqu'un éditeur ouvre le formulaire pour le modifier.