构建 Google Workspace 插件

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

当您想要构建新插件时,请遵循以下常规流程: Google Workspace

  1. 设置您的插件项目,并选择所有者和协作者。
  2. 设计插件的外观和行为。
  3. 配置插件的项目清单或部署资源。
  4. 编写代码以定义插件的外观和行为。
  5. 验证您的插件的 OAuth 范围。
  6. 在要扩展的主机应用中测试该插件。
  7. 发布该插件。

设置您的插件项目,并选择所有者和协作者

如果您在 Apps 脚本中构建插件,则需要同时创建 Apps 脚本项目和 Google Cloud 项目。如果您使用 Apps 脚本以外的语言构建插件,只需创建 Google Cloud 项目即可。

在开始进行插件开发之前,请先选择一个用户帐号来拥有项目,然后确定哪些帐号是协作者。项目的所有者会创建和管理项目文件以及关联的设置,而协作者可以帮助您编码和测试。

Apps 脚本项目

您可以在共享云端硬盘中构建插件的 Apps 脚本项目文件,这样就不会有单一帐号的唯一所有权了。通过将插件脚本文件放在共享云端硬盘中,您可以轻松确保多个协作者始终有权访问该脚本项目。

您发布插件时,单个用户帐号会充当发布商。发布帐号必须拥有脚本项目的编辑权限,但不一定是所有者。

Google Cloud 项目

我们建议您将协作者添加到插件的 Cloud 项目。这有助于确保团队中的成员始终可以访问该插件的 Cloud 设置。

设计插件的外观和行为

在开始构建插件之前,请确定它的外观和行为方式。考虑插件应该针对哪些用例提供解决方案。从简单的设计入手,首先投入工作,然后再添加更多优化。

如需了解如何设计插件用户体验,请参阅Google Workspace 插件样式指南

配置插件项目清单

在 Apps 脚本项目中,项目清单是一个特殊的 JSON 文件。它指定有关项目的各种详细信息,如其库依赖项。对于 Google Workspace 插件,清单还提供了主机应用正确显示插件所需的基本信息。

请参阅清单,详细了解如何在 Apps 脚本中配置插件的清单。

将代码和功能添加到插件时,请编辑清单,以生成所需的插件外观和行为。

对插件进行编码

您必须为插件实现基于卡片的接口。使用 Apps 脚本的卡服务,或者如果您使用其他代码语言编写代码,请为接口返回格式正确的 JSON 以呈现为卡片。

您还必须实现插件清单中指定的任何触发器函数。如果您的插件使用 OAuth 连接到第三方非 Google 服务,那么您还必须为该服务配置 OAuth

构建卡片

您可以通过创建 Card 对象并使用微件填充插件来定义插件界面。清单中指定的触发器函数必须返回单个 Card 对象或一组代表插件接口不同页面的 Card 对象。您的插件还可以创建和显示新卡片来响应用户操作。

在 Apps 脚本中,您可以使用 CardBuilder 类创建卡片。每张卡都需要一个 CardHeader 以及一个或多个 CardSections。您应该使用组成插件界面的各个微件填充每个卡片部分。互动微件通常链接到操作,以定义其互动行为。

通过卡片的 CardBuilder 向该卡片添加所有部分和微件后,您必须调用 CardBuilder.build() 来创建相应的 Card 对象。

您可以使用其他内置 Apps 脚本服务(例如 CalendarApp)来检索要在您构建的插件卡片中显示的信息。您可以使用从非 Google 服务中提取的数据。

如果您的插件 Google Workspace 需要访问需要 OAuth 的非 Google API,您必须配置并连接到该服务。如需了解详情,请参阅“连接到非 Google 服务”指南

施工顺序

构建卡片时,您必须自上而下构建。也就是说,您必须使用此构建顺序:

  1. 构建微件。
  2. 将微件添加到卡片部分。
  3. 重复上述步骤,直到卡片部分包含其所有微件。
  4. 将卡片部分添加到该卡片。

这是必须的,因为当您将微件添加到卡片或卡片部分时,您实际上是在添加该微件的副本。您在添加微件对象后对其进行的任何更改都不会反映在最终卡片中。

通用操作

您可以使用通用操作来提供与上下文无关的功能。通用操作是插件界面中可用的菜单项,无论当前显示什么卡片。所有定义的通用操作始终显示在插件的卡片菜单中。

如需了解详情,请参阅通用操作

验证插件 OAuth 范围

范围定义了插件可以代表用户执行哪些操作。对插件而言,最佳做法是使其范围限定其必须有操作才能正常运行。

在插件项目中,明确设置插件范围,以确保插件使用尽可能少的范围。 您可以在插件清单中定义插件使用的范围。

如需了解详情,请参阅范围

测试插件

您可以先安装未发布的插件,以测试未发布的插件。安装插件并对其进行授权后,您可以在自己的帐号中使用该插件,并在插件扩展的主机应用中测试其外观和行为。 您应验证插件对于上下文和用户操作是否按预期运行。

如需了解详情,请参阅测试 Google Workspace 插件

发布插件

发布插件后,您可以公开分享该插件,也可以将其发布给网域内的其他用户。在开始发布流程之前,请务必查看发布内容概览。发布是一个复杂的过程,需要准备和时间才能完成。

Google Workspace 插件已发布到 Google Workspace Marketplace。公开发布的插件必须先完成应用审核,然后才能发布。

如需了解详情,请参阅发布 Google Workspace 插件

Google Workspace 插件示例

 l10n-placeholder41=

为帮助您了解 Google Workspace 插件的构建方式,Google Workspace “Cats”插件快速入门介绍了如何构建简单的 Google Workspace插件,包括首页、卡片导航和与第三方服务的连接。完成快速入门后,您可以安装插件并试用代码。