附加操作

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

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

按照以下流程配置具有 Action 的 widget：

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

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

微件处理函数

如需将 widget 关联到 Action 或其他行为，请使用 widget 处理函数。处理程序函数用于确定哪种互动（例如点击微件或修改文本字段）会触发操作行为。处理函数还会定义界面在操作完成后采取的步骤（如果有）。

下表列出了 widget 的不同处理程序类型以及它们所使用的 widget：

处理函数 触发操作 适用的 widget 说明
setOnChangeAction 微件值发生变化 DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		设置一个 Action，用于在 widget 失去焦点时（例如用户在输入中输入文本并按 Enter 键时）执行 Apps 脚本函数。处理程序会自动将事件对象传递给它调用的函数。 如果选择此选项，您可以在此事件对象中插入其他参数信息。
setOnClickAction 用户点击微件 CardAction
Image
ImageButton
DecoratedText
TextButton 		设置一个 Action，用于在用户点击 widget 时执行 Apps 脚本函数。处理程序会自动将事件对象传递给它调用的函数。 您可以在此事件对象中插入可选的参数信息。
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 		在用户点击 widget 时直接打开网址。如果您知道网址，并且只需要打开该网址，请使用此处理程序；否则，请使用 setOnClickOpenLinkAction。 您可以在新窗口或叠加层中打开网址。关闭时，您可以使界面重新加载插件。
setSuggestionsAction 用户在输入源中输入文本 TextInput 设置一个 Action，当用户在文本输入 widget 中输入文本时，该 Action 会执行 Apps 脚本函数。处理程序会自动将事件对象传递给它调用的函数。 如需了解详情，请参阅针对文本输入的自动补全建议。

回调函数

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

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

下表显示了在执行特定操作时，您的回调函数必须返回特定响应对象的时间。这些操作都独立于插件所扩展的特定宿主应用：

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

Google Workspace 主机应用的操作

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

使用响应构建器类时，请调用 build 方法来生成响应对象。否则会导致错误。

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

操作事件对象

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

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

如需全面了解事件对象结构，请参阅事件对象。

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