附加操作

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

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

按照以下常规流程，使用 Action 配置 widget：

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

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

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 脚本函数，因此您可以让它们执行几乎任何其他脚本函数可以执行的任何操作。

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

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

下表显示了您的回调函数在什么情况下必须针对特定操作返回特定响应对象。这些操作都独立于插件要扩展的特定主机应用：

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

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

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

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

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

操作事件对象

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

操作事件对象具有特定的 JSON 结构，用于组织其包含的信息。当触发首页触发器以创建首页时，或触发内容相关触发器来更新插件显示时，会使用相同的结构。

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

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