插件操作为 widget 提供交互行为。通过创建操作,您可以定义用户选择或更新 widget 时发生的情况。
在大多数情况下,您可以使用 Apps 脚本卡片服务提供的 Action
对象来定义插件操作。在您创建每个 Action
时,它都与一个回调函数相关联。您可以实现回调函数,以便在用户与 widget 互动时执行所需步骤。您还必须使用适当的 widget 处理程序函数(用于定义触发 Action
回调的互动类型)将 Action
与 widget 相关联。
按照以下常规流程,使用 Action
配置 widget:
widget 处理程序函数
如需将某个 widget 与特定 Action
或其他行为相关联,请使用 widget 处理程序函数。处理程序函数可确定哪种类型的互动(例如,点击 widget 或修改文本字段)会触发操作行为。处理程序函数还会定义操作完成后界面采取的步骤(如果有)。
下表列出了微件的不同处理程序类型以及它们与微件配合使用:
处理程序函数 | 触发操作 | 适用的微件 | 说明 |
---|---|---|---|
setOnChangeAction() |
widget 值会发生变化 |
DatePicker DateTimePicker SelectionInput Switch TextInput
TimePicker
|
设置一个 Action ,以在 widget 失去焦点时(例如用户在输入内容并按 Enter 键时)执行 Apps 脚本函数。该处理程序会自动将事件对象传递给它调用的函数。
如果需要,您可以在此事件对象中插入其他参数信息。 |
setOnClickAction() |
用户点击微件 |
CardAction Image ImageButton DecoratedText TextButton
|
设置会在用户点击相应微件时执行 Apps 脚本函数的 Action 。该处理程序会自动将事件对象传递给它调用的函数。
您可以在此事件对象中插入可选参数信息。 |
setComposeAction() |
用户点击微件 |
CardAction Image ImageButton DecoratedText TextButton
|
Gmail 专用。设置一个用于构建电子邮件草稿的 Action ,然后在 Gmail 界面撰写窗口中向用户显示该草稿。您可以在 Gmail 中将草稿构建为新邮件或对打开的邮件的回复。当处理程序调用草稿构建回调函数时,它会将一个事件对象传递给回调函数。如需了解详情,请参阅撰写消息草稿。 |
setOnClickOpenLinkAction() |
用户点击微件 |
CardAction Image ImageButton DecoratedText TextButton
|
设置 Action 以在用户点击该 widget 时打开网址。如果您必须构建网址,或必须在链接打开之前执行其他操作,请使用此处理程序;否则,使用 setOpenLink() 通常更简单。您只能在新窗口中打开该网址。关闭插件后,您可以让界面重新加载该插件。 |
setOpenLink() |
用户点击微件 |
CardAction Image ImageButton DecoratedText TextButton
|
在用户点击微件时直接打开一个网址。如果您知道网址,并且只需要打开网址,请使用此处理程序;否则,请使用 setOnClickOpenLinkAction() 。
您可以在新窗口或叠加式窗口中打开网址。关闭插件后,您可以让界面重新加载该插件。 |
setSuggestionsAction() |
用户在输入内容中输入文本 |
TextInput
|
设置一个 Action ,以便在用户在文本输入 widget 中输入文本时执行 Apps 脚本函数。该处理程序会自动将事件对象传递给它调用的函数。
如需了解详情,请参阅针对文本输入的自动补全建议。 |
回调函数
回调函数在 Action
触发时执行。由于回调函数是 Apps 脚本函数,因此您可以让它们执行几乎任何其他脚本函数可以执行的任何操作。
回调函数有时会返回特定的响应对象。这些类型的响应表示在回调执行完毕后需要执行的其他操作,例如显示新卡片或显示自动补全建议。如果您的回调函数必须返回特定的响应对象,您可以使用卡片服务中的构建器类来构建该对象。
下表显示了您的回调函数在什么情况下必须针对特定操作返回特定响应对象。这些操作都独立于插件要扩展的特定主机应用:
已尝试执行操作 | 回调函数应返回 |
---|---|
在卡片之间导航 | ActionResponse |
显示 Notification |
ActionResponse |
使用 setOnClickOpenLinkAction() 打开链接 |
ActionResponse |
显示自动补全建议 | SuggestionResponse |
使用通用操作 | UniversalActionResponse |
其他操作信息 | Nothing |
除了这些操作之外,每个托管应用都有自己的一组操作,这些操作只能在相应主机中执行。如需了解详情,请参阅以下指南:
操作事件对象
当插件触发 Action
时,界面会自动构建一个 JSON 事件对象,并将其作为参数传递给 Action
回调函数。此事件对象包含有关用户当前客户端上下文的信息,例如所显示卡片中所有互动 widget 的当前值。
操作事件对象具有特定的 JSON 结构,用于组织其包含的信息。当触发首页触发器以创建首页时,或触发内容相关触发器来更新插件显示时,会使用相同的结构。
如需详细了解事件对象结构,请参阅事件对象。