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, die auch die Bedingung definiert, die die Aktion auslöst. Wenn die Aktion ausgelöst wird, wird eine bestimmte Callback-Funktion ausgeführt. 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(action) 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 Rückruffunktion erstellte Karte anzuzeigen.

Das folgende Beispiel zeigt die Erstellung eines Schaltflächen-Widgets. Die Aktion fordert im Namen des Add-ons den drive.file-Bereich für die aktuelle Datei an.

/**
 * 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
    // allows the user to 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 zum Anfordern des Dateizugriffs enthalten. 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 für current_document 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 Dateizugriff für das aktuelle Dokument:

  1. Erstellen Sie eine Karte für die 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, mit der Nutzer den Bereich drive.file für das aktuelle Dokument gewähren können.

Beispiel: Aktuellen Dokumentzugriff 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 simple 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 allows the user to 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
    // allows the user to 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();
}