附加操作

插件操作可为 widget 提供互动行为。通过创建操作,您可以定义用户选择或更新 widget 时发生的情况。

在大多数情况下,您可以使用 Apps 脚本 Card 服务提供的 Action 对象定义插件操作。每个 Action 在您创建回调函数时都与一个回调函数相关联。您可以实现该回调函数,以便在用户与微件互动时执行所需的步骤。您还必须使用适当的微件处理程序函数(用于定义触发 Action 回调的互动类型)将 Action 关联到该微件。

您可以按照以下常规流程使用 Action 配置 widget:

  1. 创建 Action 对象,指定它应执行的回调函数及其需要的任何参数。
  2. 使用 Action 对象在 widget 上调用适当的微件处理程序函数
  3. 实现回调函数来实施所需的行为。

微件处理程序函数

如需将某个 widget 与特定的 Action 或其他行为相关联,您可以使用 widget 处理程序函数。处理程序函数决定了哪种互动(例如,点击微件或修改文本字段)会触发操作行为。处理程序函数还定义了界面在操作完成后会执行的步骤(如果有)。

下表列出了 widget 的不同处理程序类型及其可与哪些 widget 搭配使用:

处理程序函数 触发操作 适用的 widget 说明
setOnChangeAction() 微件值会更改 DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
设置一个 Action,用于在 widget 失去焦点时执行 Apps 脚本函数,例如,当用户在输入框中输入文本并按 Enter 键时。处理程序会自动将事件对象传递给它调用的函数。 如果需要,您可以在此事件对象中插入其他参数信息。
setOnClickAction() 用户点击微件 CardAction
Image
ImageButton
DecoratedText
TextButton
设置 Action,在用户点击微件时执行 Apps 脚本函数。处理程序会自动将事件对象传递给它调用的函数。 您可以在此事件对象中插入可选参数信息。
setComposeAction() 用户点击微件 CardAction
Image
ImageButton
DecoratedText
TextButton
Gmail 专用。设置一个 Action,用于构建电子邮件草稿,然后在 Gmail 界面撰写窗口中向用户显示该草稿。您可以将草稿创建为新邮件,或回复 Gmail 中打开的邮件。当处理程序调用草稿构建回调函数时,会向回调函数传递一个事件对象。如需了解详情,请参阅撰写草稿消息
setOnClickOpenLinkAction() 用户点击微件 CardAction
Image
ImageButton
DecoratedText
TextButton
设置 Action,以在用户点击该微件时打开网址。如果必须构建网址,或者其他操作必须在链接打开之前发生,请使用此处理程序;否则,使用 setOpenLink() 通常更简单。您只能在新窗口中打开该网址。关闭后,您可以使界面重新加载该插件。
setOpenLink() 用户点击微件 CardAction
Image
ImageButton
DecoratedText
TextButton
用户点击微件时,直接打开一个网址。如果您知道网址且只需打开它,请使用此处理程序;否则,请使用 setOnClickOpenLinkAction()。 您可以在新窗口或叠加层中打开该网址。关闭后,您可以使界面重新加载该插件。
setSuggestionsAction() 用户在输入内容中 TextInput 设置一个 Action,用于在用户在文本输入 widget 中输入文本时执行 Apps 脚本函数。处理程序会自动将事件对象传递给它调用的函数。 如需了解详情,请参阅针对文本输入的自动补全建议

回调函数

回调函数在 Action 触发时执行。由于回调函数是 Apps 脚本函数,因此您可以让其执行任何其他脚本函数所能完成的几乎所有操作。

回调函数有时会返回特定的响应对象。这些类型的响应表示回调执行完毕后需要执行的其他操作,例如显示新卡片或显示自动补全建议。当您的回调函数必须返回特定的响应对象时,您可以使用 Card 服务中的构建器类构造该对象。

下表显示了您的回调函数何时必须针对特定操作返回特定的响应对象。这些操作均独立于该插件正在扩展的特定主机应用:

已尝试执行操作 回调函数应返回
在卡片之间导航 ActionResponse
显示 Notification ActionResponse
使用 setOnClickOpenLinkAction() 打开链接 ActionResponse
显示自动补全建议 SuggestionResponse
使用通用操作 UniversalActionResponse
其他操作信息

除了这些操作之外,每个托管应用还有自己的一组只能在该主机中执行的操作。如需了解详情,请参阅以下指南:

操作事件对象

当插件触发 Action 时,界面会自动构建一个 JSON 事件对象,并将其作为参数传递给 Action 回调函数。此事件对象包含有关用户当前客户端上下文的信息,如所显示的卡片中所有互动 widget 的当前值。

操作事件对象具有特定的 JSON 结构,用于整理它们包含的信息。当首页触发器触发以创建首页,或触发上下文触发器以更新插件显示时,系统会使用这一结构。

如需查看事件对象结构的完整说明,请参阅事件对象