此页面由 Cloud Translation API 翻译。

构建 Google 编辑器界面

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

访问插件界面

如果 Google Workspace 插件的图标显示在 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 文档、表格和幻灯片，并在每个托管应用中显示通用首页。

 "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 部分。该插件已在文档、表格和幻灯片中启用。它会在文档和幻灯片中显示通用首页，在表格中显示专属首页。回调函数 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 部分中命名的函数。此函数接受 event 对象作为参数，并且必须返回单个 Card 对象或 Card 对象数组。
与任何卡片一样，您必须实现用于为界面提供 widget 互动性的回调函数。例如，如果您在界面中添加按钮，则该按钮应附加 Action 和在点击按钮时运行的已实现回调函数。

以下示例展示了 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 函数的 Editor 事件对象。在这里，该插件对当前文档拥有 drive.file 范围授权：

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