构建 Google 编辑器界面

借助 Google Workspace 插件，您可以在编辑器（包括 Google 文档、Google 表格和 Google 幻灯片）中提供自定义界面。这样，您就可以向用户提供相关信息、自动执行任务，并将第三方系统连接到编辑器。

访问插件界面

如果 Google Workspace 插件的图标显示在 Google 文档、Google 表格和 Google 幻灯片界面的 Google Workspace 快速访问侧边栏中，您可以在编辑器中打开该插件。

Google Workspace 插件可以显示以下界面：

首页界面：如果插件的清单包含用户在其中打开插件的编辑器的 EDITOR_NAME.homepageTrigger 触发器，则插件会专门为该编辑器构建并返回首页卡片。如果插件的清单不包含用户在其中打开插件的编辑器的 EDITOR_NAME.homepageTrigger ，则会改为显示通用首页卡片。
**REST API 界面**：如果插件使用 REST API，您可以添加使用 drive.file 范围请求对文档进行文件级访问的触发器。获得授权后，另一个名为 EDITOR_NAME.onFileScopeGrantedTrigger 的触发器会执行并显示特定于该文件的界面。
**链接预览界面**：如果您的插件与第三方服务集成，您可以构建用于预览服务网址中的内容的卡片。

为编辑器插件构建界面

按照以下步骤为编辑器构建编辑器插件界面：

将相应的 addOns.common、 addOns.docs、 addOns.sheets、和 addOns.slides 字段添加到插件脚本项目清单。
将任何必需的编辑器范围添加到您的脚本项目清单。
如果您要提供特定于编辑器的首页，请实现 EDITOR_NAME.homepageTrigger 函数来构建界面。否则，请使用 common.homepageTrigger 界面为宿主应用构建通用首页。
如果您使用 REST API，请实现 drive.file 范围授权流程和 EDITOR_NAME.onFileScopeGrantedTrigger 触发器函数，以显示特定于打开文件的界面。如需了解详情，请参阅 REST API 界面。
如果您要配置来自第三方服务的链接预览，请实现 https://www.googleapis.com/auth/workspace.linkpreview 范围授权流程和 linkPreviewTriggers 函数。如需了解详情，请参阅链接预览界面。
实现响应用户界面互动（例如按钮点击）所需的相关回调函数。

编辑器首页

您必须在插件的脚本项目中提供首页触发器函数，该函数会构建并返回单个 Card 或构成插件首页的 Card 对象数组。

首页触发器函数会收到一个事件对象作为参数，该对象包含客户端平台等信息。您可以使用事件对象数据来定制首页的构建。

您可以显示通用首页，也可以显示特定于用户在其中打开插件的编辑器的首页。

显示通用首页

如需在编辑器中显示插件的通用首页，请在插件的清单中添加相应的编辑器字段，例如 addOns.docs、 addOns.sheets或 addOns.slides。

以下示例展示了 Google Workspace 插件清单的 addons 部分。该插件扩展了 Google 文档、Google 表格和 Google 幻灯片，并在每个宿主应用中显示通用首页。

{
 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

显示特定于编辑器的首页

如需显示特定于编辑者的首页，请将 EDITOR_NAME.homepageTrigger 添加到插件清单。

以下示例展示了 Google Workspace 插件清单的 addons 部分。该插件已针对 Google 文档、Google 表格和 Google 幻灯片启用。它在 Google 文档和 Google 幻灯片中显示通用首页，并在 Google 表格中显示唯一首页。回调函数 onSheetsHomepage 会构建特定于 Google 表格的首页卡片。

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

REST API 界面

如果您的插件使用 REST API（例如 Google Sheets API），您可以使用 onFileScopeGrantedTrigger 函数显示特定于在编辑器宿主应用中打开的文件的新界面。

您必须添加 drive.file 范围授权流程才能使用 onFileScopeGrantedTrigger 函数。如需了解如何请求 drive.file 范围，请参阅请求当前文档的文件访问权限。

当用户授予 drive.file 范围时， EDITOR_NAME.onFileScopeGrantedTrigger.runFunction 会触发。触发器触发后，它会执行上下文触发器函数，该函数由插件清单中的 EDITOR_NAME.onFileScopeGrantedTrigger.runFunction字段指定。

如需为其中一个编辑器创建 REST API 界面，请完成以下步骤。将 EDITOR_NAME 替换为您选择使用的编辑器宿主应用，例如 sheets.onFileScopeGrantedTrigger：

将 EDITOR_NAME.onFileScopeGrantedTrigger 添加到清单的相应编辑器部分。例如，如果您想在 Google 表格中创建此界面，请将触发器添加到 "sheets" 部分。
实现 EDITOR_NAME.onFileScopeGrantedTrigger 部分中命名的函数。此函数接受事件对象作为参数，并且必须返回单个 Card 对象或 Card 对象数组。
与任何卡片一样，您必须实现用于为界面提供小部件互动性的回调函数。例如，如果您在界面中添加了按钮，则该按钮应具有附加的操作和已实现的回调函数，该函数会在点击按钮时运行。

以下示例展示了 Google Workspace 插件清单的 addons 部分。该插件使用 REST API，因此 Google 表格中包含 onFileScopeGrantedTrigger。当用户授予 drive.file 范围时，回调函数 onFileScopeGrantedSheets 会构建特定于文件的界面。

{
  "addOns": {
    "common": {
      "name": "Productivity add-on",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
      "layoutProperties": {
        "primaryColor": "#669df6",
        "secondaryColor": "#ee675c"
      }
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedSheets"
      }
    }
  }
}

第三方服务的链接预览界面

如需为第三方服务启用链接预览，您必须在插件的清单中配置链接预览，并创建一个返回预览卡片的函数。对于需要用户授权的服务，您的函数还必须调用授权流程。

如需了解启用链接预览的步骤，请参阅包含智能条状标签的预览链接。

事件对象

系统会创建事件对象并将其传递给触发器函数，例如 EDITOR_NAME.homepageTrigger 或 EDITOR_NAME.onFileScopeGrantedTrigger。触发器函数使用事件对象中的信息来确定如何构建插件卡片或以其他方式控制插件行为。

事件对象的完整结构在事件对象中进行了说明。

当编辑器是插件的实际宿主应用时，事件对象会包含 Google 文档、 Google 表格或 Google 幻灯片事件对象字段，这些字段会携带客户端信息。

如果插件没有当前用户或文档的 drive.file 范围授权，则事件对象仅包含 docs.addonHasFileScopePermission、sheets.addonHasFileScopePermission 或 slides.addonHasFileScopePermission 字段。如果插件具有授权，则事件对象包含所有编辑器事件对象字段。

以下示例展示了传递给 sheets.onFileScopeGrantedTrigger 函数的编辑器事件对象。在此示例中，插件具有 drive.file 范围授权当前文档：

{
  "commonEventObject": { ... },
  "sheets": {
    "addonHasFileScopePermission": true,
    "id":"A_24Q3CDA23112312ED52",
    "title":"How to get started with Sheets"
  },
  ...
}

构建 Google 编辑器界面 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。