Editor-Aktionen

Mit Action-Objekten können Sie interaktive Funktionen in Google Workspace-Add‑ons einbauen.

Aktionsobjekte definieren, was passiert, wenn ein Nutzer mit einem Widget (z. B. einer Schaltfläche) in der Add-on-Benutzeroberfläche interagiert.

Aktion einem Widget hinzufügen

Wenn Sie einem Widget eine Aktion zuweisen möchten, verwenden Sie eine Widget-Handler-Funktion, in der auch die Bedingung definiert wird, die die Aktion auslöst. Wenn sie ausgelöst wird, führt die Aktion eine bestimmte Callback-Funktion aus. An die Callback-Funktion wird ein Ereignisobjekt übergeben, das Informationen zu den clientseitigen Interaktionen des Nutzers enthält. Sie müssen die Callback-Funktion implementieren und ein bestimmtes Antwortobjekt zurückgeben lassen.

Beispiel: Neue Karte anzeigen, wenn auf eine Schaltfläche geklickt wird

Wenn Sie Ihrem Add-on eine Schaltfläche hinzufügen möchten, mit der beim Klicken eine neue Karte erstellt und angezeigt wird, gehen Sie so vor:

  1. Erstellen Sie ein Schaltflächen-Widget.
  2. Wenn Sie eine Aktion zum Erstellen von Karten festlegen möchten, fügen Sie die Handler-Funktion für das Schaltflächen-Widget setOnClickAction hinzu.
  3. Erstellen Sie eine Apps Script-Callback-Funktion, die ausgeführt werden soll, und geben Sie sie als action in der Widget-Handler-Funktion an. In diesem Fall sollte die Callback-Funktion die gewünschte Karte erstellen und ein ActionResponse-Objekt zurückgeben. Das Antwortobjekt weist das Add-on an, die von der Callback-Funktion erstellte Karte anzuzeigen.

Das folgende Beispiel zeigt die Erstellung eines Schaltflächen-Widgets. Mit der Aktion wird im Namen des Add-ons der Bereich drive.file für die aktuelle Datei angefordert.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION"
 * button. When it's clicked, the callback triggers file scope permission flow.
 * This is used in the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // If the add-on does not have access permission, add a button that
    // lets the user provide that permission on a per-file basis.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document's ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}

Interaktionen für den Dateizugriff für REST APIs

Google Workspace-Add‑ons, die die Editoren erweitern und REST APIs verwenden, können eine zusätzliche Widget-Aktion enthalten, um Dateizugriff anzufordern. Für diese Aktion muss die zugehörige Aktions-Callback-Funktion ein spezielles Antwortobjekt zurückgeben:

Versuchte Aktion Die Callback-Funktion sollte zurückgeben
Dateizugriff anfordern EditorFileScopeActionResponse

Damit Sie dieses Widget-Aktions- und Antwortobjekt verwenden können, müssen alle folgenden Bedingungen erfüllt sein:

  • Das Add-on verwendet REST APIs.
  • Das Add-on präsentiert das Dialogfeld für den Anforderungsbereich für Dateien mit der Methode CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
  • Das Add-on enthält in seinem Manifest den Editorbereich https://www.googleapis.com/auth/drive.file und den Trigger onFileScopeGranted.

Dateizugriff für das aktuelle Dokument anfordern

So beantragen Sie den Dateizugriff für das aktuelle Dokument:

  1. Erstellen Sie eine Karte auf der Startseite, die prüft, ob das Add-on den Bereich drive.file hat.
  2. Wenn dem Add-on der Bereich drive.file nicht gewährt wurde, müssen Sie eine Möglichkeit schaffen, dass Nutzer den Bereich drive.file für das aktuelle Dokument gewähren.

Beispiel: Zugriff auf das aktuelle Dokument in Google Docs abrufen

Im folgenden Beispiel wird eine Benutzeroberfläche für Google Docs erstellt, auf der die Größe des aktuellen Dokuments angezeigt wird. Wenn das Add-on keine drive.file-Autorisierung hat, wird eine Schaltfläche angezeigt, mit der die Autorisierung des Dateibereichs initiiert werden kann.

/**
 * Build a card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this add-on provides a button
 * to request `drive.file` scope for items the add-on doesn't yet have
 * permission to access.
 *
 * @param e The event object passed containing information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that lets the user provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['title']);
    // This add-on uses the recommended, limited-permission `drive.file`
    // scope to get granular per-file access permissions.
    // See: https://developers.google.com/drive/api/v2/about-auth
    // If the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " +
          getQuotaBytesUsed(docsEventObject['id'])));
  } else {
    // If the add-on does not have access permission, add a button that
    // lets the user provide that permission on a per-file basis.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "The add-on needs permission to access this file's quota."));

    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClicked");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to
 * display a permissions dialog to the user, requesting `drive.file` scope for
 * the current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document's ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}