Google Workspace 插件的触发器

Apps 脚本触发器会在每次发生指定事件时,触发指定的脚本函数(即触发器函数)。只有特定事件可以导致触发器触发,并且每个 Google Workspace 应用支持一组不同的事件。

当触发器触发时,系统会创建一个事件对象。此 JSON 结构包含有关已发生事件的详细信息。事件对象结构中的信息的组织方式因触发器类型而异。

创建事件对象后,Apps 脚本会将其作为参数传递给触发器函数。触发器函数是一个回调函数,您必须自行实现,以便执行任何适合响应事件的操作。例如,在扩展 Gmail 的 Google Workspace 插件中,您可以定义一个触发器,以便在用户打开邮件会话时创建新的卡片界面。在这种情况下,您需要实现一个上下文回调函数,以使用在事件对象中传递的数据创建组成新界面的卡片。

本页面提供了有关在 Google Workspace 插件项目中使用触发器的准则。

清单触发器

与编辑器插件不同,Google Workspace 插件目前无法使用 Apps 脚本的简单触发器,而是使用专为 Google Workspace 插件设计的触发器:清单触发器

清单触发器完全在 Google Workspace 插件的清单中定义。清单触发器的示例包括:

  • 首页触发器,用于构建并显示插件首页。
  • 日历活动打开触发器,可在打开日历活动时显示新卡片或执行其他操作。
  • Calendar eventUpdate 触发器:可以在用户修改并保存日历活动时显示新卡片或执行其他操作。
  • Drive onItemsSelected 触发器,可在用户选择云端硬盘中的一个或多个文件或文件夹时,显示新卡片或执行其他操作。
  • Gmail 撰写触发器:当用户在 Gmail 撰写窗口中打开插件时显示插件卡片。
  • Gmail 上下文触发器,可在用户打开 Gmail 邮件时显示新卡片或执行其他操作。
  • Editor onFileScopegranted 触发器 - 当用户在当前编辑器文档中授予对 drive.file OAuth 范围的授权时,系统会显示一张新卡片。

在上面的列表中,只有首页触发器是非内容触发器;其余是内容触发器。如需详细了解清单触发器的定义,请参阅清单

除了清单触发器之外,Google Workspace 插件还可以使用 Apps 脚本的可安装触发器

限制

清单触发器对其用法有特定限制。

  • 这些触发器仅用于 Google Workspace 插件项目;在任何其他应用中没有任何用途。
  • 由于这些触发器是在插件清单(而不是其代码)中定义的,因此您无法使用 Apps 脚本 Script 服务创建或修改这些触发器。
  • Gmail 上下文触发器目前只能有 unconditional 条件。 这意味着,无论电子邮件内容如何,上下文触发器都会触发。
  • 对于每个用户的每个文档,每个插件只能有一个每种类型的触发器。