构建 Google 编辑器界面

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

访问插件界面

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

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

  • 首页界面:如果插件的清单包含编辑器的触发器 EDITOR_NAME.homepageTrigger,而用户在其中打开插件,则插件会构建并专门为该编辑器返回首页卡片。如果插件的清单中不包含用户用于打开该插件的编辑器的 EDITOR_NAME.homepageTrigger,则会显示通用的首页卡片。

  • REST API 接口:如果插件使用 REST API,您可以添加使用 drive.file 范围请求按文件访问文档的触发器。被授予后,另一个名为 EDITOR_NAME.onFileScopeGrantedTrigger 的触发器会执行,并显示该文件专用的接口。

  • 链接预览界面:如果您的插件与第三方服务集成,您可以构建卡片来预览来自您服务网址的内容。

为编辑器插件构建界面

按照以下步骤为编辑器构建编辑器插件接口:

  1. 在插件脚本项目 清单中添加相应的 addOns.commonaddOns.docsaddOns.sheetsaddOns.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.docsaddOns.sheetsaddOns.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 表格中显示唯一首页。回调函数 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.homepageTriggerEDITOR_NAME.onFileScopeGrantedTrigger。触发器函数使用事件对象中的信息来确定如何构建插件卡或以其他方式控制插件行为。

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

如果编辑器是插件的执行主应用,则事件对象包括承载客户端信息的文档表格幻灯片事件对象字段。

如果插件没有当前用户或文档的 drive.file 范围授权,则事件对象仅包含 docs.addonHasFileScopePermissionsheets.addonHasFileScopePermissionslides.addonHasFileScopePermission 字段。如果该插件有授权,则事件对象会包含所有编辑器事件对象字段。

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

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