最佳实践

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

一般最佳实践

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

在开始之前确定插件所有权

插件是由 Apps 脚本项目定义的,必须归特定帐号所有或位于共享云端硬盘中。在对插件进行编码之前,请确定哪个帐号应该拥有该项目,以及哪个帐号将作为其发布商。此外,还要确定哪些帐号充当协作者,并确保这些帐号可以访问脚本项目及其关联的 Cloud Platform 项目

扩展 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 或其他复杂界面对象的代码时,不妨考虑将该代码放在其自己的函数中。此创建函数应仅构建并返回对象。这样,每当必须刷新界面时,您就可以快速重新生成该对象。使用 Card 服务中的构建器类后,请记得调用 build()

确保卡片简洁明了

如果指定卡片包含的 widget 过多,可能会占据过多屏幕,会降低其实用性。虽然较大的卡片部分会呈现为可收起的界面元素,但这会对用户隐藏信息。旨在简化您的插件,并准确提供用户的需求。

使用错误卡片

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

编写测试和测试消息

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

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

    Logger.log(response.printJson());

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

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

日历会议最佳做法

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

onCreateFunction 保持灯亮

当用户尝试创建该类型的会议解决方案时,您在清单中定义的每个 onCreateFunction 都会被同步调用。请确保这些函数只执行创建会议所需的最少工作。在这些函数中执行过多操作可能会导致插件的用户体验变慢。

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

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

不要将会议详细信息附加到 Google 日历活动

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