吸引用户采取行动

借助 Action 对象，您可以为 Google Workspace 插件构建互动行为。它们定义了当用户与插件界面中的 widget（例如按钮）互动时会发生什么。

操作通过 widget 处理函数附加到给定的 widget，该函数还定义了触发操作的条件。触发后，操作会执行指定的回调函数。回调函数会收到一个事件对象，其中包含有关用户客户端互动的信息。您必须实现回调函数，并让其返回特定的响应对象。

例如，假设您希望创建一个按钮，当用户点击该按钮时，系统会构建并显示一张新卡片。为此，您必须创建一个新的按钮 widget，并使用按钮 widget 处理函数 setOnClickAction(action) 设置卡片构建器 Action。您定义的 Action 用于指定在点击按钮时执行的 Apps 脚本回调函数。在这种情况下，您需要实现回调函数来构建所需的卡片，并返回 ActionResponse 对象。响应对象会告知插件显示回调函数构建的卡片。

本页介绍了您可以在插件中添加的特定于 Google 云端硬盘的 widget 操作。

促成互动

扩展云端硬盘的 Google Workspace 插件可以包含额外的云端硬盘专用 widget 操作。此操作要求关联的操作回调函数返回一个专用响应对象：

尝试的操作 回调函数应返回
为所选文件请求文件访问权限 DriveItemsSelectedActionResponse

如需使用这些 widget 操作和响应对象，必须满足以下所有条件：

  • 当用户选择了一个或多个云端硬盘内容时，系统会触发此操作。
  • 该插件在其清单中包含 https://www.googleapis.com/auth/drive.file Drive 范围。

为所选文件请求文件访问权限

以下示例展示了如何为 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;
  }
}