构建 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 的触发器，并显示特定于该文件的界面。

  • 链接预览界面：如果您的插件与第三方服务集成，则可以构建用于预览服务网址中的内容的卡片。

为编辑器插件构建界面

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

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

编辑器首页

您必须在插件的脚本项目中提供一个首页触发函数，该函数用于构建并返回单个 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 部分。 该插件已为 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。

  1. 在清单的相应编辑器部分中添加 EDITOR_NAME.onFileScopeGrantedTrigger。例如，如果您想在 Google 表格中创建此界面，请将触发器添加到 "sheets" 部分。
  2. 实现 EDITOR_NAME.onFileScopeGrantedTrigger 部分中命名的函数。此函数接受一个事件对象作为实参，并且必须返回单个 Card 对象或 Card 对象数组。
  3. 与任何卡片一样，您必须实现用于为界面提供 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。触发函数使用事件对象中的信息来确定如何构建插件卡片或以其他方式控制插件行为。

如需详细了解事件对象的完整结构，请参阅事件对象。

当编辑器是插件的实际宿主应用时，事件对象会包含携带客户端信息的 Docs、Sheets 或 Slides 事件对象字段。

如果该插件没有当前用户或文档的 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"
          },
          ...
        }