附加操作

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

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

如需使用 Action 配置微件，请按以下步骤操作：

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

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

微件处理函数

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

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

处理函数 触发操作 适用的微件 说明
setOnChangeAction 微件值发生变化 DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		设置一个 Action ，用于在微件失去焦点时（例如用户在输入框中输入文本并按 Enter 键时）执行 Apps 脚本函数。处理程序会自动将事件对象传递给它调用的函数。您可以根据需要在此事件对象中插入其他参数信息 。
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 ，用于在用户将文本输入到文本输入微件时执行 Apps 脚本函数。处理程序会自动将 事件对象传递给它调用的函数。 如需了解详情，请参阅 文本输入的自动补全建议。

回调函数

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

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

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

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

适用于 Google Workspace 宿主应用的操作

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

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

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

操作事件对象

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

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

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

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