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
条件。 这意味着,无论电子邮件内容如何,上下文触发器都会触发。 - 对于每个用户的每个文档,每个插件只能有一个每种类型的触发器。