此页面由 Cloud Translation API 翻译。

编辑器操作

使用 Action 对象在 Google Workspace 插件中构建交互行为。

操作对象用于定义用户与插件界面中的 widget（例如按钮）互动时会发生的情况。

为微件添加操作

如需将操作附加到 widget，请使用 widget 处理程序函数，该函数还会定义触发操作的条件。触发时，该操作会执行指定的回调函数。系统会向回调函数传递一个事件对象，其中包含有关用户客户端互动的信息。您必须实现回调函数，并使其返回特定的响应对象。

示例：点击按钮时显示新卡片

如果您想向您的插件添加一个按钮，以便在点击时构建并显示新卡片，请按以下步骤操作：

创建一个按钮微件。
如需设置卡片制作操作，请添加按钮 widget 处理程序函数 setOnClickAction(action)。
创建要执行的 Apps 脚本回调函数，并在 widget 处理脚本函数中将其指定为 (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 的文件访问互动

扩展 Google 编辑器并使用 REST API 的 Google Workspace 插件可以包含用于请求文件访问权限的额外 widget 操作。此操作要求关联的操作回调函数返回专用响应对象：

尝试执行的操作	回调函数应返回
请求对 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();
}