Diese Seite wurde von der Cloud Translation API übersetzt.

Editor-Aktionen

Mit Action-Objekten können Sie Google Workspace-Add-ons interaktiv gestalten.

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

Widget eine Aktion hinzufügen

Wenn Sie einem Widget eine Aktion zuweisen möchten, verwenden Sie eine Widget-Handlerfunktion, die auch die Bedingung definiert, die die Aktion auslöst. Wenn die Aktion ausgelöst wird, wird eine bestimmte Callback-Funktion ausgeführt. Der 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: Eine neue Karte anzeigen, wenn auf eine Schaltfläche geklickt wird

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

Erstellen Sie ein Schaltflächen-Widget.
Wenn Sie eine Aktion zum Erstellen von Karten festlegen möchten, fügen Sie die Handlerfunktion für das Schaltflächen-Widget setOnClickAction(action) hinzu.
Erstellen Sie eine Apps Script-Callback-Funktion, die ausgeführt werden soll, und geben Sie sie als (action) in der Widget-Handlerfunktion 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 Karte anzuzeigen, die von der Rückruffunktion erstellt wurde.

Das folgende Beispiel zeigt die Erstellung eines Schaltflächen-Widgets. Die Aktion fordert im Namen des Add-ons den Bereich drive.file 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 Callback-Funktion der Aktion ein spezielles Antwortobjekt zurückgeben:

Versuchte Aktion	Die Callback-Funktion sollte Folgendes zurückgeben:
Dateizugriff für current_document anfordern	`EditorFileScopeActionResponse`

Damit du diese Widget-Aktion und dieses Antwortobjekt verwenden kannst, müssen die folgenden Bedingungen erfüllt sein:

Das Add-on verwendet REST APIs.
Das Add-on zeigt das Dialogfeld „Anfrage – Dateiumfang“ mit der Methode CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); an.
Das Add-on enthält im 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:

Erstellen Sie eine Startseitenkarte, auf der geprüft wird, ob das Add-on den Umfang drive.file hat.
Wenn dem Add-on nicht die Berechtigungsstufe drive.file gewährt wurde, müssen Sie eine Möglichkeit einrichten, mit der Nutzer die Berechtigungsstufe 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, über die die Autorisierung auf Dateiebene gestartet 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();
}