编辑器操作

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

操作对象定义用户与 widget 互动时会发生什么 （例如按钮）。

向微件添加操作

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

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

如果您想向插件添加用于构建并显示新卡片的按钮 请按照以下步骤操作：

1. 创建一个按钮 widget。
2. 如需设置卡片构建操作，请添加按钮 widget 处理程序函数 setOnClickAction(action)。
3. 创建要执行的 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 插件可以包含一个 用于请求文件访问权限的其他 widget 操作。此操作需要 关联的操作回调函数，以便返回专用响应对象：

已尝试执行操作	回调函数应返回
请求对 current_document 的文件访问权限	EditorFileScopeActionResponse

要使用此 widget 操作和响应对象，必须具备以下所有条件： 为 true：

• 该插件使用 REST API。
• 插件会显示“请求文件范围”对话框 使用 CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); 方法。
• 该插件包含 https://www.googleapis.com/auth/drive.file 编辑器范围和 onFileScopeGranted 触发器。

请求访问当前文档的文件访问权限

如需请求对当前文档的文件访问权限，请按以下步骤操作：

1. 构建首页卡片，用于检查该插件是否具有 drive.file 范围。
2. 如果插件未获得 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();
}