附加操作

插件操作可为微件提供互动行为。通过创建操作,您可以定义用户选择或更新微件时会发生什么。

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

按照以下常规流程使用 Action 配置微件:

  1. 创建 Action 对象,指定它应该执行的回调函数以及它需要的所有参数。
  2. 使用 Action 对象在微件上调用相应的微件处理程序函数
  3. 实现回调函数以实施所需的行为。

微件处理程序函数

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

下表列出了微件的不同处理程序类型以及它们与哪些微件配合使用:

处理程序函数 触发操作 适用的微件 说明
setOnChangeAction() 微件值会更改 DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
设置会在 widget 失去焦点时执行 Apps 脚本函数的 Action,例如用户在用户输入文本时按 Enter 键。该处理程序会自动将事件对象传递给它调用的函数。如果需要,您可以在此事件对象中插入其他参数信息。
setOnClickAction() 用户点击微件 CardAction
Image
ImageButton
DecoratedText
TextButton
设置会在用户点击 widget 时执行 Apps 脚本函数的 Action。该处理程序会自动将事件对象传递给它调用的函数。您可以在此事件对象中插入可选参数信息。
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,用于在用户输入文本输入微件时执行 Apps 脚本函数。该处理程序会自动将事件对象传递给它调用的函数。如需了解详情,请参阅文本输入自动补全建议

回调函数

回调函数会在 Action 触发时执行。由于回调函数是 Apps 脚本函数,因此您可以让它们执行几乎任何其他脚本函数都可以执行的操作。

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

下表显示了回调函数何时必须针对特定操作返回特定响应对象。这些操作都与插件正在扩展的特定主机应用无关:

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

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

操作事件对象

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

操作事件对象具有特定的 JSON 结构,用于整理其包含的信息。当首页触发器触发来创建首页,或者触发上下文触发器来更新附加屏幕时,系统会使用相同的结构。

有关事件对象结构的完整说明,请参阅事件对象