构建 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 执行并 会显示该文件专属的接口。

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

为编辑器插件构建界面

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

  1. 添加适当的 addOns.commonaddOns.docsaddOns.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.docsaddOns.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

  1. 添加 EDITOR_NAME.onFileScopeGrantedTrigger 。例如,如果您 要在 Google 表格中创建此界面,请将触发器添加到 "sheets" 部分。
  2. 实现 EDITOR_NAME.onFileScopeGrantedTrigger 中指定的函数 部分。此函数接受事件对象作为参数,并且必须返回单个 Card 对象或 Card 对象的数组。
  3. 与任何卡片一样,您必须实现用于提供 界面的 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.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"
          },
          ...
        }