Action
对象可让您在 Google Workspace 插件中构建互动行为。它们定义了用户与插件界面中的微件(例如按钮)互动时发生的情况。
您可以使用微件处理程序函数将操作附加到指定的微件,该函数还定义触发操作的条件。触发后,操作会执行指定的回调函数。系统会向回调函数传递事件对象,其中包含有关用户客户端互动的信息。您必须实现该回调函数,并让其返回特定的响应对象。
例如,假设您想要一个按钮,点击该按钮会构建并显示新卡片。为此,您必须创建新的按钮 widget,并使用按钮 widget 处理程序函数 setOnClickAction(action)
来设置卡片构建 Action
。您定义的 Action
会指定在用户点击按钮时执行的 Apps 脚本回调函数。在这种情况下,您需要实现回调函数来构建所需的卡并返回 ActionResponse
对象。响应对象会告知插件显示所构建的回调函数。
本页面介绍了您可以添加到插件中的云端硬盘专用微件操作。
吸引用户互动
用于扩展云端硬盘的 Google Workspace 插件可以包含云端硬盘专用的额外微件操作。此操作需要关联的操作回调函数返回专门的响应对象:
已尝试执行操作 | 回调函数应返回 |
---|---|
请求获得所选文件的文件访问权限 | DriveItemsSelectedActionResponse |
如需使用这些 widget 操作和响应对象,必须满足以下所有条件:
- 在用户选择一项或多项云端硬盘内容时触发操作。
- 该插件在其清单中包含
https://www.googleapis.com/auth/drive.file
云端硬盘范围。
请求获得所选文件的文件访问权限
以下示例展示了如何为 Google 云端硬盘构建上下文界面,该界面会在用户选择一项或多项云端硬盘内容时触发。此示例会测试每个项目以查看插件是否已获得访问权限;如果没有,它会使用 DriveItemsSelectedActionResponse
对象向用户请求该权限。为某个项授予相应权限后,该插件会显示该项的云端硬盘配额用量。
/**
* 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 contextual information about
* the Drive items selected.
* @return {Card}
*/
function onDriveItemsSelected(e) {
var builder = CardService.newCardBuilder();
// For each item the user has selected in Drive, display either its
// quota information or a button that allows the user to provide
// permission to access that file to retrieve its quota details.
e['drive']['selectedItems'].forEach(
function(item){
var cardSection = CardService.newCardSection()
.setHeader(item['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 (item['addonHasFileScopePermission']) {
// If the add-on has access permission, read and display its
// quota.
cardSection.addWidget(
CardService.newTextParagraph().setText(
"This file takes up: " + getQuotaBytesUsed(item['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")
.setParameters({id: item.id});
var button = CardService.newTextButton()
.setText("Request permission")
.setOnClickAction(buttonAction);
cardSection.addWidget(button);
}
builder.addSection(cardSection);
});
return builder.build();
}
/**
* Callback function for a button action. Instructs Drive to display a
* permissions dialog to the user, requesting `drive.file` scope for a
* specific item on behalf of this add-on.
*
* @param {Object} e The parameters object that contains the item's
* Drive ID.
* @return {DriveItemsSelectedActionResponse}
*/
function onRequestFileScopeButtonClicked (e) {
var idToRequest = e.parameters.id;
return CardService.newDriveItemsSelectedActionResponseBuilder()
.requestFileScope(idToRequest).build();
}
/**
* Use the Advanced Drive Service
* (See https://developers.google.com/apps-script/advanced/drive),
* with `drive.file` scope permissions to request the quota usage of a
* specific Drive item.
*
* @param {string} itemId The ID of the item to check.
* @return {string} A description of the item's quota usage, in bytes.
*/
function getQuotaBytesUsed(itemId) {
try {
return Drive.Files.get(itemId,{fields: "quotaBytesUsed"})
.quotaBytesUsed + " bytes";
} catch (e) {
return "Error fetching how much quota this item uses. Error: " + e;
}
}