构建 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 设置。

设计插件的外观和行为

在开始构建插件之前，您需要确定它的外观及其行为。考虑插件应该尝试为哪些用例提供解决方案。先从简单的设计着手，再开始使用，然后添加更多优化。

提示：请先添加一个简单的首页卡片，然后添加更多微件、卡片、导航和其他行为。您还可以考虑用户在托管应用中执行的操作（例如打开 Gmail 邮件会话或 日历活动）所触发的上下文卡片。

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

配置插件项目清单

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

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

将插件和功能添加到插件时，请根据需要修改清单，以生成所需的插件外观和行为。

对插件进行编码

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

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

构建卡片

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

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

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

注意 ：如果在卡片服务中使用构建器类后未能调用 build()，则会导致类型错误。例如，触发器函数必须返回 Card 对象。返回 CardBuilder 对象会导致错误。

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

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

施工顺序

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

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

必须执行此操作，因为当您向卡片或卡片部分添加微件时，您实际上是在添加该微件的副本。您在添加 widget 对象后对其所做的任何更改都不会反映在最终卡片中。

警告 ：请仅在完成卡片或卡片部分的构建后再向其添加微件。仅在将卡片部分完全填充到卡片中后再向其添加卡片部分。请勿在添加 widget 或版块后对其进行更改。如果您要更改添加的 widget，则必须重新创建添加该 widget 的部分或卡片。

通用操作

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

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

验证插件 OAuth 范围

范围定义了插件可以代表用户执行的操作。最佳做法是，插件仅针对其按顺序操作所必须执行的操作拥有作用域。

在插件项目中，明确设置插件范围，以便确保该插件使用的是尽可能宽松的范围。您可以在插件清单中定义插件使用的范围。

如需了解详情，请参阅范围。

测试插件

您可以首先安装未发布的插件，以测试未发布的插件。安装并授权后，您就可以在帐号中使用该插件，并在其扩展的宿主应用中测试其外观和行为。您应验证插件对于上下文和用户操作的行为是否符合预期。

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

发布插件

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

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

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

Google Workspace 插件示例

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