使用 Action 对象将互动行为构建到 Google Workspace 插件中。
操作对象定义了用户与插件界面中的微件(例如按钮)互动时发生的情况。
向 widget 添加操作
如需将操作附加到 widget,请使用 widget 处理程序函数,该函数还定义触发操作的条件。触发后,操作会执行指定的回调函数。系统会向回调函数传递事件对象,其中包含有关用户客户端互动的信息。您必须实现该回调函数,并让其返回特定的响应对象。
示例:在用户点击按钮时显示新卡片
如果您想要向插件添加一个按钮,该按钮会在用户点击后构建并显示新卡片,请按以下步骤操作:
- 创建一个按钮 widget。
- 如需设置卡片构建操作,请添加按钮 widget 处理程序函数
setOnClickAction(action)
。 - 创建一个 Apps 脚本回调函数,以便执行该函数并在微件处理程序函数中将其指定为
(action)
。在这种情况下,回调函数应构建您需要的卡并返回ActionResponse
对象。响应对象会告知插件显示回调函数所构建的卡片。
以下示例展示了如何创建按钮 widget。该操作会代表插件请求当前文件的 drive.file
范围。
/** * 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();
REST API 的文件访问交互
扩展编辑器并使用 REST API 的 Google Workspace 插件可包含用于请求文件访问权限的附加微件操作。此操作要求关联的操作回调函数返回专门的响应对象:
已尝试执行操作 | 回调函数应返回 |
---|---|
请求 current_document 的文件访问权限 | EditorFileScopeActionResponse |
如需使用此 widget 操作和响应对象,必须满足以下所有条件:
- 该插件使用 REST API。
- 该插件使用
CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();
方法显示请求文件范围对话框。 - 该插件的清单中包含
https://www.googleapis.com/auth/drive.file
编辑器范围和onFileScopeGranted
触发器。
请求访问当前文档的文件
要请求当前文档的文件访问权限,请按以下步骤操作:
- 构建一个首页卡片,用于检查插件是否具有
drive.file
范围。 - 如果插件尚未获得
drive.file
范围,请构建一种方法来请求用户为当前文档授予drive.file
范围。
示例:在 Google 文档中获取当前文档的访问权限
以下示例将为 Google 文档构建一个显示当前文档大小的界面。如果插件没有 drive.file
授权,则会显示用于启动文件范围授权的按钮。
/**
* 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();
}