Einfache Trigger

Mit Triggern kann Google Apps Script eine Funktion automatisch ausführen, wenn ein bestimmtes Ereignis eintritt, z. B. wenn ein Dokument geöffnet wird. Einfache Trigger sind eine Reihe von reservierten 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, Sheets, Präsentationen oder Formulare öffnet. Installierbare Trigger bieten mehr Funktionen als einfache Trigger, müssen aber vor der Verwendung aktiviert werden. Bei beiden Triggertypen ü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 Web-App aufruft oder ein Programm eine HTTP-GET-Anfrage an eine Web-App sendet.
• doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Web-App sendet.

Der Parameter e 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:

• Das Script muss an eine Datei in Google Sheets, Google Präsentationen, Google Docs oder Google Formulare gebunden sein oder ein Add‑on sein, das eine dieser Anwendungen erweitert.
• Sie werden nicht ausgeführt, wenn eine Datei im Lesemodus (Ansehen oder Kommentieren) geöffnet wird.
• Scriptausführungen und API-Anfragen führen nicht dazu, dass Trigger ausgeführt werden. Wenn Sie beispielsweise Range.setValue() aufrufen, um eine Zelle zu bearbeiten, wird der onEdit-Trigger der Tabelle nicht ausgeführt.
• Sie können nicht auf Dienste zugreifen, für die eine Autorisierung erforderlich ist. Ein einfacher Trigger kann beispielsweise keine E‑Mail senden, da für den Gmail-Dienst eine Autorisierung erforderlich ist. Ein einfacher Trigger kann jedoch einen Ausdruck mit dem anonymen Language-Dienst übersetzen.
• Sie können die Datei bearbeiten, an die sie gebunden sind, aber nicht auf andere Dateien zugreifen, da dies eine Autorisierung erfordern würde.
• Je nach komplexen Sicherheitsbeschränkungen können sie die Identität des aktuellen Nutzers möglicherweise ermitteln.
• Sie dürfen nicht länger als 30 Sekunden laufen.
• Unter bestimmten Umständen werden Editor-Add-ons mit ihren einfachen Triggern onOpen(e) und onEdit(e) in einem Modus ohne Autorisierung ausgeführt, was einige zusätzliche Komplikationen mit sich bringt. Weitere Informationen finden Sie im Leitfaden zum Autorisierungslebenszyklus von Add-ons.
• Einfache Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.

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

onOpen(e)

Der Trigger onOpen(e) wird automatisch ausgelöst, 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 benutzerdefinierte Menüelemente in Google Sheets, Google Präsentationen, Google Docs oder Google Formulare einzufügen.

/**
 * 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 Trigger onInstall(e) wird automatisch ausgeführt, wenn ein Nutzer ein Editor-Add-on in Google Docs, Sheets, Präsentationen oder Formularen installiert. Der Trigger wird nicht ausgelöst, wenn ein Nutzer das Add-on über die Google Workspace Marketplace-Website installiert. onInstall(e) wird am häufigsten verwendet, um onOpen(e) aufzurufen und benutzerdefinierte Menüs hinzuzufügen. Nachdem ein Add-on installiert wurde, ist die Datei bereits geöffnet. onOpen(e) wird daher 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

/**
 * 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 angemessen zu reagieren. Mit der Funktion onEdit(e) im folgenden Beispiel wird beispielsweise ein Kommentar für die Zelle festgelegt, in der die letzte Bearbeitungszeit aufgezeichnet wird.

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

Mit dem onEdit()-Trigger werden nur bis zu zwei Triggerereignisse in die Warteschlange gestellt.

onSelectionChange(e)

Der onSelectionChange(e)-Trigger wird automatisch ausgeführt, wenn ein Nutzer die Auswahl in einer Tabelle ändert. Damit dieser Trigger aktiviert wird, müssen Sie die Tabelle aktualisieren, nachdem Sie den Trigger hinzugefügt haben, und jedes Mal, wenn die Tabelle geöffnet wird.

Wenn die Auswahl in kurzer Zeit zwischen mehreren Zellen wechselt, werden einige Ereignisse für die Änderung der Auswahl möglicherweise übersprungen, um die Latenz zu verringern. Wenn beispielsweise innerhalb von zwei Sekunden mehrere Änderungen an der Auswahl vorgenommen werden, wird der onSelectionChange(e)-Trigger nur durch die erste und die letzte Änderung ausgelöst.

Im folgenden Beispiel wird der Hintergrund einer leeren ausgewählten Zelle mit der Funktion onSelectionChange(e) rot gefärbt.

/**
 * 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 Trigger doGet(e) wird automatisch ausgelöst, wenn ein Nutzer eine Web-App aufruft oder ein Programm eine HTTP-GET-Anfrage an eine Web-App sendet. doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Web-App sendet. Diese Trigger werden in den Anleitungen zu Web-Apps, HTML-Dienst und Content-Dienst genauer beschrieben. doGet(e) und doPost(e) unterliegen nicht den oben aufgeführten Einschränkungen.

Verfügbare Triggertypen

Wenn die Einschränkungen für einfache Trigger dazu führen, dass sie Ihre Anforderungen nicht erfüllen, kann stattdessen ein installierbarer Trigger verwendet werden. In der folgenden Tabelle sehen Sie, welche Arten von Triggern für die einzelnen Ereignistypen verfügbar sind. Beispielsweise unterstützen Google Sheets, Google Präsentationen, Google Formulare und Google Docs alle einfachen Open-Trigger, aber nur Google Sheets, Google Docs und Google Formulare unterstützen installierbare Open-Trigger.

Ereignis	Einfache Trigger	Installierbare Trigger
Öffnen	function onOpen(e)
Bearbeiten	function onEdit(e)
Auswahl ändern	function onSelectionChange(e)
Installieren	function onInstall(e)
Ändern
Formular senden
Zeitgesteuert (Uhr)
Produktiver	function doGet(e)
Posten	function doPost(e)

* Das Ereignis „Öffnen“ für Google-Formulare wird nicht ausgelöst, wenn ein Nutzer ein Formular öffnet, um darauf zu antworten, sondern wenn ein Bearbeiter das Formular öffnet, um es zu ändern.