Google Workspace 插件的触发器

每当指定的事件发生时,Apps 脚本触发器就会执行指定的脚本函数(触发器函数)。只有特定事件才能触发触发器,并且每个 Google Workspace 应用都支持一组不同的事件。

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

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

本页面提供了有关如何在 Google Workspace 插件项目中使用触发器的指南。

清单触发器

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

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

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

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

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

限制

清单触发器对它们的使用有特定限制。

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