最佳实践

请遵循这些插件设计指南,以提升用户的整体体验。

一般最佳实践

建议您为开发的所有插件遵循以下最佳实践。

先确定插件的所有权,然后再开始

插件由 Apps 脚本项目定义,这些项目 必须归特定账号所有,否则必须放置在 共享 云端硬盘中。在为插件编写代码之前,请确定哪个账号应拥有该项目,以及哪个账号应作为其发布商。此外,还要确定哪些账号将作为协作者,并确保这些账号有权访问脚本项目及其关联的Google Cloud 项目

扩展 Google Workspace,而不是复制它

插件旨在为它们扩展的 Google Workspace 应用提供新功能,或者自动执行复杂的任务。 如果插件只是复制应用中已有的功能,或者没有对工作流进行重大改进,则不太可能通过 插件审核 以进行发布。

保持范围狭窄

明确定义范围 时,请始终选择 尽可能最小的权限范围集。例如,如果插件只需要读取权限,则不要让它使用 https://www.googleapis.com/auth/calendar 范围请求对用户日历的完全访问权限。对于只读权限,请使用 https://www.googleapis.com/auth/calendar.readonly 范围。

避免过度依赖库

使用 Apps 脚本 可能会 导致插件的 运行速度 比将所有 Apps 脚本代码都包含在 单个脚本项目中时 慢。虽然 Apps 脚本库可以在插件中使用,但使用它们可能会导致性能下降。避免在项目中包含不必要的库,并考虑如何减少插件对它们的依赖。

上述延迟仅适用于用作服务器端库的 Apps 脚本项目。您可以随意使用 jQuery 等客户端 JavaScript 库,而不会遇到这种延迟。

Google Workspace 插件最佳实践

以下最佳实践仅适用于 Google Workspace 插件和 Card 服务的使用。

仅使用少量卡片

如果插件使用的卡片过多,导航配置会变得复杂且难以管理。

避免创建超出必要数量的卡片。

使用 widget 创建函数

在编写用于创建 Card或其他复杂界面对象的代码时, 请考虑将该代码放在自己的函数中。此创建函数应仅构建对象并返回该对象。这样,您就可以在必须刷新界面时快速重新生成该对象。请记得在使用 Card service中的构建器类后调用 build()

保持卡片简单

如果给定卡片包含的 widget 过多,则可能会占用过多屏幕空间,从而降低实用性。虽然大型卡片部分会呈现为可折叠的界面元素,但这会向用户隐藏信息。请力求简化插件,并仅提供用户所需的内容。

使用错误卡片

为错误情况创建卡片。如果插件产生错误,则应显示一张卡片,其中包含错误信息以及有关如何更正错误的说明(如果可能)。例如,如果插件因授权失败而无法连接到非 Google 服务,请显示一张卡片说明此情况,并要求用户验证所使用的账号信息。

编写测试和测试消息

您应彻底测试您创建的所有插件。构建使用测试数据创建卡片和 widget 的测试函数,然后验证是否按预期创建了对象。

使用操作回调 函数时,通常 必须构建响应对象。您可以使用如下语句来验证响应是否正确构建:

    Logger.log(response.printJson());

使用运行 菜单直接从 Apps 脚本编辑器运行您创建的测试函数。当您有一个可行的 插件正常运行时,请务必安装未发布的 版本,以便进行测试。

使用适合插件扩展的每个宿主应用的测试数据。例如,如果插件扩展了 Gmail,您可能需要一些测试电子邮件及其消息 ID,以便确保插件在收到不同的消息内容时按预期运行。您可以使用 Gmail API users.messages.list 方法列出 消息,或使用 Apps 脚本的 Gmail 服务,获取给定消息的消息 ID。

Google 日历会议最佳实践

如果您的插件将 第三方日历 会议选项集成到 Google 日历中,请遵循以下其他最佳实践:

保持 onCreateFunction 光线

您在清单中定义的每个 onCreateFunction 会在用户尝试 创建该类型的会议解决方案时同步调用。确保这些函数仅执行创建会议所需的最低限度工作。在这些函数中执行过多操作可能会导致插件的用户体验不佳。

为会议数据使用适当的 ConferenceData 字段

构建 ConferenceData 对象时,您可以向其中填充有关会议的详细信息(访问代码、 电话号码、PIN 码、URI 等)。请务必为此信息使用相应的 EntryPoint字段。请勿将这些详细信息放在 ConferenceData 备注字段中。

请勿将会议详细信息附加到 Google 日历活动

您的插件无需将有关创建的第三方会议的信息添加到 Google 日历活动说明中。Google 日历会在必要时自动执行此操作。