附加操作

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

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

您可以按照以下一般流程使用 Action 配置 widget：

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

注意： 请勿将 Action 对象与 CardAction 对象混淆。CardAction 对象是卡片标题菜单项，而 Action 对象用于定义对用户与界面的互动做出的响应。

微件处理脚本函数

如需将微件关联到特定 Action 或其他行为，您可以使用微件处理脚本函数。处理程序函数决定了哪种类型的互动（例如点击微件或修改文本字段）会触发操作行为。处理脚本函数还定义了界面在操作完成后要执行的步骤（如果有）。

下表列出了 widget 的不同处理程序类型以及它们适用于哪些 widget：

处理程序函数	触发操作	适用的 widget	说明
setOnChangeAction()	微件值发生变化	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	设置一个 Action，用于在 widget 失去焦点时执行 Apps Script 函数，例如当用户在输入框中输入文本并按 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 脚本函数，因此您可以让它们执行几乎任何其他脚本函数可以执行的操作。

警告： Apps 脚本卡片服务限制回调函数的执行时间上限为 30 秒。如果执行时间超过该时间，您的插件界面可能无法正确更新其卡片显示，以响应 Action。

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

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

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

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

• 日历操作
• 吸引用户采取行动
• Gmail 操作
• 编辑器操作

注意： 使用响应构建器类时，请务必调用 build() 来生成响应对象。否则会导致错误。

注意： 通用操作在项目清单中定义，不需要 Action 对象，但其回调函数必须返回 UniversalActionResponse。

操作事件对象

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

操作事件对象具有特定的 JSON 结构，用于整理其包含的信息。当首页触发器触发以创建首页，或情境触发器触发以更新插件显示时，都会使用相同的结构。

如需详细了解事件对象结构，请参阅事件对象。

注意 ：Gmail 插件使用了此事件对象结构的简化版本，该版本现已废弃。为了实现向后兼容，所有原始 Gmail 插件事件对象字段仍包含在新事件对象结构中（请参阅事件对象结构）。不过，通用事件和 Gmail 事件对象子结构中会重现相同的信息。如果您要将 Gmail 插件升级为 Google Workspace 插件，则应调整代码以使用更新后的事件对象字段，最终原始的 Gmail 事件对象字段将被移除。