附加操作

插件操作提供了 widgets 的基础。 通过创建操作，您可以定义当用户选择或更新时会发生什么情况 一个 widget。

在大多数情况下，您可以使用 Action 由 Apps 脚本卡片服务提供的对象。 每个 Action 都与 回调函数。您需要实现回调函数 在用户与 widget 互动时执行所需的步骤。您还必须 将 Action 关联到 widget 使用相应的微件处理程序函数 指定触发何种互动 Action 回调。

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

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

。

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

widget 处理程序函数

将 widget 与特定 Action 相关联 或其他行为，您需要使用 处理程序函数。处理程序函数决定了 （例如，点击 widget 或修改文本字段）会触发 操作行为。处理程序函数还定义了界面执行的步骤， 如果有，则在操作完成后显示。

下表列出了微件的不同处理程序类型以及 与它们配合使用的微件：

处理程序函数	触发操作	适用的微件	说明
setOnChangeAction()	widget 值会发生变化	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	设置 Action 该函数会在 widget 失去焦点时执行 Apps 脚本函数，例如 例如当用户输入文本并按 Enter 键时。通过 处理程序会自动将 事件对象传递给其调用的函数。 您可以在此事件对象中插入其他参数信息 （如果需要的话）。
setOnClickAction()	用户点击微件	CardAction Image ImageButton DecoratedText TextButton	设置 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。处理程序会自动将 事件对象传递给其调用的函数。 请参阅 自动补全建议 “文本输入”。

回调函数

当出现 Action 时，系统会执行回调函数。 触发器。由于回调函数是 Apps 脚本函数，因此您可以将其 可以执行任何其他脚本函数几乎可以完成的一切。

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

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

下表显示了回调函数在什么情况下必须返回 特定响应对象。这些操作都是 与该插件扩展的特定主机应用无关：

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

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

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

。

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

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

操作事件对象

当您的插件触发 Action 时， 界面会自动构建一个 JSON 事件对象，并将其作为 Action 回调的参数 函数。此事件对象包含有关用户当前 客户端上下文，例如所有互动操作的当前值。 微件。

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

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

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