Mit Action-Objekten interaktive Elemente erstellen Google Workspace-Add-ons.
Aktionsobjekte definieren, was passiert, wenn ein Nutzer mit einem Widget interagiert. (z. B. eine Schaltfläche) in der Add-on-Benutzeroberfläche.
Aktion zu einem Widget hinzufügen
Verwenden Sie zum Anhängen einer Aktion an ein Widget eine Widget-Handler-Funktion. definiert auch die Bedingung, die die Aktion auslöst. Wenn der Parameter ausgelöst wird, Aktion eine festgelegte Callback-Funktion ausführt. An die Callback-Funktion wird ein Ereignisobjekt übergeben. die Informationen zu den clientseitigen Interaktionen der Nutzenden enthält. Du musst 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 eine neue Karte erstellt und angezeigt wird Wenn Sie darauf klicken, folgen Sie diesen Schritten:
- Erstellen Sie ein Schaltflächen-Widget.
- Füge zum Festlegen einer Kartenerstellungsaktion die Widget-Handler-Funktion für die Schaltfläche hinzu.
setOnClickAction(action)
- Erstellen Sie eine Apps Script-Callback-Funktion, die ausgeführt werden soll und als die
(action)
in der Widget-Handler-Funktion. In diesem Fall wird die Callback-Funktion sollte die gewünschte Karte erstellen und einActionResponse
-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. Die Aktionsanfragen
Den Bereich drive.file
für die aktuelle Datei im Namen des Add-ons.
/** * 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();
Dateizugriffsinteraktionen für REST APIs
Google Workspace-Add-ons, die die Editoren erweitern und REST APIs verwenden, können Folgendes umfassen: zusätzliche Widget-Aktion zum Anfordern des Dateizugriffs. Für diese Aktion ist das verknüpfte Aktionsrückruffunktion, um ein spezielles Antwortobjekt zurückzugeben:
Aktion versucht | Die Callback-Funktion sollte Folgendes zurückgeben: |
---|---|
Dateizugriff auf „current_document“ anfordern | EditorFileScopeActionResponse |
Um diese Widget-Aktion und dieses Antwortobjekt nutzen zu können, müssen alle der folgenden Bedingungen erfüllt sein: wahr sein:
- Das Add-on verwendet REST APIs.
- Das Add-on zeigt das Dialogfeld zum Anfordern des Dateiumfangs an.
mit der Methode
CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();
. - Das Add-on enthält die
https://www.googleapis.com/auth/drive.file
Editor-Bereich undonFileScopeGranted
-Trigger in seinem Manifest enthält.
Dateizugriff auf das aktuelle Dokument anfordern
So fordern Sie Dateizugriff für das aktuelle Dokument an:
- Erstellen Sie eine Startseitenkarte, die prüft, ob das Add-on den Bereich
drive.file
hat. - Wenn dem Add-on der Bereich
drive.file
nicht gewährt wurde, erstellen Sie einen Möglichkeit, Nutzer aufzufordern, 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 Schnittstelle für Google Docs erstellt, auf der die Größe
des aktuellen Dokuments. Wenn das Add-on keine drive.file
-Autorisierung hat,
wird eine Schaltfläche zum Initiieren der Dateizugriffsautorisierung 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();
}