此页面由 Cloud Translation API 翻译。

构建 Google 编辑器界面

借助 Google Workspace 插件，你可以在编辑器中提供自定义界面，包括 Google 文档、表格和幻灯片。这样，您就可以为用户提供自动完成任务，并将第三方系统连接到编辑者。

访问插件界面

您可以在编辑器中打开 Google Workspace 插件其图标是否出现在 Google Workspace 快速访问 Google 文档、表格和幻灯片用户右侧的侧边栏界面。

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 部分清单。该插件可以扩展文档、表格和幻灯片的功能，并显示每个托管应用中的主页

 "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 表格中的唯一首页。回调函数 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 对象的数组。
与任何卡片一样，您必须实现用于提供界面的 widget 交互性。例如，如果您在界面中添加一个按钮它应该有附加的 Action，以及一个在点击该按钮时运行的已实现的回调函数。

以下示例展示了 Google Workspace 插件清单的 addons 部分。该插件使用 REST API，因此包含 onFileScopeGrantedTrigger Google 表格。当用户授予 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。触发器函数使用事件对象来确定如何构建附加卡片或以其他方式控制插件行为。

事件对象中介绍了事件对象的完整结构。

如果编辑器是插件的托管应用，则事件对象包括文档、表格或幻灯片包含客户端信息的事件对象字段。

如果插件没有针对当前用户的 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"
          },
          ...
        }