构建 Google 日历界面

当用户查看或修改日历和日历活动时，Google Workspace 加载项可以提供自定义界面。这样一来，您就可以向用户提供更多相关信息、自动执行任务，以及将第三方系统连接到日历。

为 Google 日历构建 Google Workspace 插件界面时，您可以提供首页。您可以为多个主机使用同一首页，也可以专门为日历设计首页。

插件还可以定义在用户打开日历活动时显示的界面。

访问插件界面

界面可以多种方式显示，具体取决于上下文。例如，插件可以定义首页界面、日历活动界面、附件选择界面，也可以同时定义这三个界面：

  • 如果用户在日历视图中点击插件图标，插件会执行相应的 calendar.homepageTrigger 函数（如果有）。此函数会构建并返回一个首页卡片，以供日历显示。如果未定义 calendar.homepageTrigger 函数，则会改为显示通用首页卡片。
  • 如果用户打开日历活动，然后点击插件图标，或者用户打开活动时插件处于打开状态，则插件会执行相应的 eventOpenTrigger 函数（如果有）。此函数构建附加组件的日历活动界面，并返回到日历以供显示。
  • 如果插件定义了 eventAttachmentTrigger 函数，那么当用户在修改日历活动时点击添加附件时，该插件会显示为附件提供方。选择该插件后，eventAttachmentTrigger 函数会构建插件的附件选择界面，并将其返回给日历以供显示。

构建插件日历界面

请按照以下步骤构建界面。您可以按照以下步骤操作，通过 Google Workspace 插件扩展日历：

  1. 确定您是否希望插件具有特定于日历的首页。此外，还要决定是否要在用户修改日历活动时提供自定义界面。
  2. 将相应的 addOns.common 和 addOns.calendar 字段添加到插件脚本项目的清单中，包括任何必需的范围。
  3. 如果您要提供特定于日历的首页，请实现 calendar.homepageTrigger 函数来构建此界面。您还可以选择使用 common.homepageTrigger 接口来支持多个宿主应用。
  4. 如果您要提供日历活动界面，请实现 calendar.eventOpenTrigger 函数来构建此界面。如需了解详情，请参阅扩展日历事件界面。
  5. 实现响应用户界面互动（例如点击按钮）所需的关联回调函数。

日历首页

插件支持显示 Google Workspace 插件首页。如需在日历中显示插件的通用首页，请确保插件的清单中包含 addOns.calendar 字段。

或者，向插件清单添加 calendar.homepageTrigger，以提供特定于 Google 日历的首页。

无论哪种情况，您都必须在插件的脚本项目中提供首页触发函数的名称。此函数会在需要时自动调用，以构建日历首页。实现此函数以构建并返回构成首页的单个 Card 或 Card 对象数组。首页触发函数会收到一个事件对象作为参数，其中包含一些常规信息，例如客户端的平台。使用事件对象数据来定制首页的构建。

扩展日历活动界面

日历依赖于上下文触发器来确定用户修改日历活动时要显示的界面（如果有）。当触发器触发时，它会执行插件清单中 calendar.eventOpenTrigger 字段指定的上下文触发器函数。

实现 calendar.eventOpenTrigger 字段中指定的函数。此函数接受一个事件对象作为参数，并且必须返回单个 Card 对象或一个 Card 对象数组，以便 Google 日历在用户打开相应活动时显示这些对象。

事件对象

当用户打开日历活动时，系统会创建 event 对象并将其传递给 calendar.eventOpenTrigger 上下文触发函数。触发函数可以使用此事件对象中的信息来确定如何构建插件卡片或控制插件行为。当插件首次打开时，以及当用户点击或选择互动 widget 时，系统也会创建事件对象并将其传递给 homepageTrigger 函数。

如需详细了解事件对象的完整结构，请参阅事件对象。当日历是插件的实际宿主应用时，上下文触发器和 widget 互动事件对象会包含 Calendar event object 字段，其中包含特定于日历的客户端信息。

更新日历活动

除了在用户打开日历活动进行修改时触发的上下文 calendar.eventOpenTrigger 之外，您还可以定义在用户更新并保存日历活动时触发的 calendar.eventUpdateTrigger。仅当用户进行以下一项或多项修改时，此触发器才会触发：

  • 添加一个或多个参会者。
  • 移除一位或多位参会者。
  • 添加或切换到其他会议解决方案。

当此触发器触发时，它会执行 calendar.eventUpdateTrigger 清单字段指定的触发器函数。该函数会在保存日历活动编辑内容之前执行。

calendar.eventUpdateTrigger通常用于以下一个或多个方面：

  • 根据用户对日历活动的更改，更新插件的日历活动界面。
  • 将日历活动数据与第三方系统（例如已连接到日历的会议系统）同步。

如果您需要插件调整日历活动的数据（例如参加者名单），请将插件的 calendar.currentEventAccess 清单字段设置为 WRITE 或 READ_WRITE。这还要求该插件具有 https://www.googleapis.com/auth/calendar.addons.current.event.write scope。

添加会议解决方案

如果您维护第三方会议系统，可以通过添加会议解决方案将其与 Google 日历集成。此功能之前以 Google 日历会议插件的形式提供 Beta 版。

会议解决方案表示用户可以附加到日历活动的第三方会议选项。第三方会议概览文档详细介绍了如何构建可添加新会议解决方案的插件。无需为此类扩展程序构建界面；添加的解决方案会作为选项显示在日历活动界面的下拉菜单中。