Mit Action-Objekten können Sie Google Workspace-Add-ons interaktives Verhalten ermöglichen.
Aktionsobjekte definieren, was passiert, wenn ein Nutzer mit einem Widget (z. B. einer Schaltfläche) in der Add-on-Benutzeroberfläche interagiert.
Aktion zu einem Widget hinzufügen
Um eine Aktion an ein Widget anzuhängen, verwenden Sie eine Widget-Handler-Funktion, die auch die Bedingung definiert, die die Aktion auslöst. Bei Auslösung führt die Aktion eine vorgesehene 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: Beim Klicken auf eine Schaltfläche eine neue Karte anzeigen
Wenn Sie Ihrem Add-on eine Schaltfläche hinzufügen möchten, mit der beim Anklicken eine neue Karte erstellt und angezeigt wird, gehen Sie so vor:
- Erstellen Sie ein Schaltflächen-Widget.
- Fügen Sie die Handler-Funktion
setOnClickAction(action)
für das Schaltflächen-Widget hinzu, um eine Kartenerstellungsaktion festzulegen. - Erstellen Sie eine Apps Script-Callback-Funktion, die ausgeführt werden soll, und geben Sie sie in der Widget-Handler-Funktion als
(action)
an. In diesem Fall sollte die Callback-Funktion die gewünschte Karte erstellen und einActionResponse
-Objekt zurückgeben. Das Antwortobjekt weist das Add-on an, die Karte anzuzeigen, die die Callback-Funktion erstellt hat.
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 mit Dateizugriff für REST APIs
Google Workspace-Add-ons, die die Editoren erweitern und REST APIs verwenden, können eine zusätzliche Widgetaktion enthalten, um Dateizugriff anzufordern. Für diese Aktion muss die zugehörige Callback-Funktion der Aktion ein spezialisiertes Antwortobjekt zurückgeben:
Aktion versucht | Callback-Funktion sollte |
---|---|
Dateizugriff für aktuelles_Dokument 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 zeigt das Dialogfeld für den Bereich der Anfragedatei mithilfe 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 TriggeronFileScopeGranted
.
Dateizugriff für aktuelles Dokument anfordern
So fordern Sie Dateizugriff für das aktuelle Dokument an:
- Erstellen Sie eine Startseitenkarte, mit der geprüft wird, ob das Add-on den Geltungsbereich
drive.file
hat. - Erstellen Sie für Fälle, in denen dem Add-on nicht der Bereich
drive.file
gewährt wurde, eine Möglichkeit, Nutzer auffordern zu lassen, dem Add-on den Bereichdrive.file
für das aktuelle Dokument zu gewähren.
Beispiel: Aktuellen Zugriff auf Dokumente in Google Docs erhalten
Im folgenden Beispiel wird eine Oberfläche für Google Docs erstellt, die die Größe des aktuellen Dokuments anzeigt. Wenn das Add-on keine drive.file
-Autorisierung hat, wird eine Schaltfläche zum Starten der Autorisierung auf Dateiebene angezeigt.
/**
* 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();
}