Einfache Trigger

Mit Triggern kann Google Apps Script automatisch eine Funktion ausführen, wenn ein bestimmtes Ereignis eintritt, z. B. wenn ein Dokument geöffnet wird. Einfache Trigger sind eine Reihe reservierter Funktionen, die in Apps Script integriert sind, z. B. die Funktion onOpen(e), die ausgeführt wird, wenn ein Nutzer eine Datei in Google Docs, Google Sheets, Google Präsentationen oder Google Formulare öffnet. Installierbare Trigger bieten mehr Funktionen als einfache Trigger, müssen aber vor der Verwendung aktiviert werden. Bei beiden Arten von Triggern übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen zum Kontext enthält, in dem das Ereignis aufgetreten ist.

Informationen zur Verwendung von Triggern in Google Workspace-Add-on Projekten finden Sie unter Trigger für Google Workspace-Add-ons.

Erste Schritte

Wenn Sie einen einfachen Trigger verwenden möchten, erstellen Sie eine Funktion mit einem der folgenden reservierten Funktionsnamen:

  • onOpen(e) wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument, eine Präsentation oder ein Formular öffnet, das er bearbeiten darf.
  • onInstall(e) wird ausgeführt, wenn ein Nutzer ein Editor-Add-on in Google Docs, Google Sheets, Google Präsentationen oder Google Formulare installiert.
  • onEdit(e) wird ausgeführt, wenn ein Nutzer einen Wert in einer Tabelle ändert.
  • onSelectionChange(e) wird ausgeführt, wenn ein Nutzer die Auswahl in einer Tabelle ändert.
  • doGet(e) wird ausgeführt, wenn ein Nutzer eine Webanwendung aufruft oder ein Programm eine HTTP-GET-Anfrage an eine Webanwendung sendet.
  • doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Webanwendung sendet.

Der e Parameter in den Funktionsnamen oben ist ein Ereignisobjekt, das an die Funktion übergeben wird. Das Objekt enthält Informationen zum Kontext, der den Trigger ausgelöst hat. Die Verwendung ist jedoch optional.

Einschränkungen

Da einfache Trigger automatisch ausgelöst werden, ohne den Nutzer um Autorisierung zu bitten, unterliegen sie mehreren Einschränkungen:

Diese Einschränkungen gelten nicht für doGet(e) oder doPost(e).

onOpen(e)

Der Trigger onOpen(e) wird automatisch ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument, eine Präsentation oder ein Formular öffnet, das er bearbeiten darf. Der Trigger wird nicht ausgeführt, wenn Sie auf ein Formular antworten, sondern nur, wenn Sie das Formular zum Bearbeiten öffnen. onOpen(e) wird am häufigsten verwendet, um Google Sheets, Google Präsentationen, Google Docs oder Google Formulare benutzerdefinierte Menüelemente hinzuzufügen.

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

Der onInstall(e) Trigger wird automatisch ausgeführt, wenn ein Nutzer ein Editor-Add-on in Google Docs, Google Sheets, Google Präsentationen oder Google Formulare installiert. Der Trigger wird nicht ausgeführt, wenn ein Nutzer das Add-on über die Google Workspace Marketplace Website installiert. Am häufigsten wird onInstall(e) verwendet, um onOpen(e) aufzurufen und benutzerdefinierte Menüs hinzuzufügen. Nach der Installation eines Add-ons ist die Datei bereits geöffnet. Daher wird onOpen(e) nicht automatisch ausgeführt, es sei denn, die Datei wird wieder geöffnet. Beachten Sie, dass es bestimmte Einschränkungen gibt, was onInstall(e) tun kann. Weitere Informationen zur Autorisierung.

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

Der Trigger onEdit(e) wird automatisch ausgeführt, wenn ein Nutzer den Wert einer Zelle in einer Tabelle ändert. Die meisten onEdit(e) Trigger verwenden die Informationen im Ereignisobjekt, um entsprechend zu reagieren. Die Funktion onEdit(e) unten legt beispielsweise einen Kommentar in der Zelle fest, in der die letzte Bearbeitungszeit aufgezeichnet wird.

triggers/triggers.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()}`);
}

Der Trigger onEdit() reiht nur bis zu zwei Triggerereignisse in die Warteschlange ein.

onSelectionChange(e)

Der Trigger onSelectionChange(e) wird automatisch ausgeführt, wenn ein Nutzer die Auswahl in einer Tabelle ändert. Wenn Sie diesen Trigger aktivieren möchten, aktualisieren Sie die Tabelle, nachdem der Trigger hinzugefügt wurde und jedes Mal, wenn die Tabelle geöffnet wird.

Wenn die Auswahl in kurzer Zeit zwischen mehreren Zellen wechselt, werden einige Ereignisse zur Auswahländerung möglicherweise übersprungen, um die Latenz zu verringern. Wenn beispielsweise viele Auswahländerungen innerhalb von zwei Sekunden vorgenommen werden, aktivieren nur die erste und die letzte Auswahländerung den Trigger onSelectionChange(e).

Im folgenden Beispiel wird der Hintergrund der Zelle rot festgelegt, wenn eine leere Zelle ausgewählt ist.onSelectionChange(e)

triggers/triggers.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) und doPost(e)

Der doGet(e) Trigger wird automatisch ausgeführt, wenn ein Nutzer eine Webanwendung aufruft oder ein Programm eine HTTP-GET-Anfrage an eine Webanwendung sendet. doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Webanwendung sendet. Diese Trigger werden in den Leitfäden zu Webanwendungen, zum HTML-Dienst, und zum Content-Dienst ausführlicher beschrieben. Beachten Sie, dass doGet(e) und doPost(e) nicht den oben aufgeführten Einschränkungen unterliegen.

Verfügbare Triggerarten

Wenn die Einschränkungen für einfache Trigger Ihre Anforderungen nicht erfüllen, kann stattdessen ein installierbarer Trigger verwendet werden. In der folgenden Tabelle sind die verfügbaren Triggerarten für die einzelnen Ereignistypen zusammengefasst. Google Sheets, Google Präsentationen, Google Formulare und Google Docs unterstützen beispielsweise alle einfache Open-Trigger, aber nur Google Sheets, Google Docs und Google Formulare unterstützen installierbare Open-Trigger.

Ereignis Einfache Trigger Installierbare Trigger
Öffnen
Google Sheets
Google Präsentationen
Google Formulare*
Google Docs

function onOpen(e)
Google Sheets
Google Formulare*
Google Docs
Bearbeiten
Google Sheets

function onEdit(e)
Google Sheets
Auswahländerung
Google Sheets

function onSelectionChange(e)
Installieren
Google Sheets
Google Präsentationen
Google Formulare
Google Docs

function onInstall(e)
Ändern
Google Sheets
Formular senden
Google Sheets
Google Formulare
Zeitgesteuert (Uhr)
Google Sheets
Google Präsentationen
Google Formulare
Google Docs
Eigenständig
Abrufen
Eigenständig

function doGet(e)
Posten
Eigenständig

function doPost(e)

* Das Open-Ereignis für Google Formulare tritt nicht auf, wenn ein Nutzer ein Formular öffnet, um zu antworten, sondern wenn ein Bearbeiter das Formular öffnet, um es zu ändern.