此页面由 Cloud Translation API 翻译。

附加操作

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

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

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

创建 Action 对象，指定它应执行的回调函数以及它需要的所有参数。
使用 Action 对象在 widget 上调用相应的 widget 处理程序函数。
实现回调函数以采取所需的行为。

微件处理程序函数

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

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

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

回调函数

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

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

下表显示了回调函数必须何时针对特定操作返回特定响应对象。这些操作都与插件扩展的特定主机应用无关：

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

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

操作事件对象

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

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

有关事件对象结构的完整说明，请参阅事件对象。