1.7.0 及以上版本

上一节我们介绍了如何实现联动，是比较基础和局限的，而事件动作是更简单、更灵活、更高级的用法，可以解决复杂的 UI 交互场景，支持渲染器事件监听和响应设计，无需关心组件层级关系。例如：

• http 请求：发送 http 请求
• 弹窗提示：执行弹窗、抽屉打开和 toast 提示
• 页面跳转：页面链接跳转
• 浏览器相关：回退、前进、后退、刷新
• 刷新组件：联动刷新表单数据，即数据重新加载
• 组件状态：控制指定组件的显示/隐藏、启用/禁用、展示态/编辑态
• 组件特性动作：执行指定组件的专有动作，例如执行表单的提交动作
• 组件数据：更新指定组件的数据域
• 广播：多个组件监听同一个事件做出不同响应
• JS 脚本：通过编写 JS 代码片段实现所需逻辑，同时支持 JS 代码内执行动作
• 逻辑编排：条件、循环、排他、并行

基本使用

onEvent

通过onEvent属性实现渲染器事件与响应动作的绑定。onEvent内配置事件和动作映射关系，actions是事件对应的响应动作的集合。

{
  "type": "button",
  "label": "尝试点击、鼠标移入/移出",
  "level": "primary",
  "onEvent": {
    "click": { // 监听点击事件
      "actions": [ // 执行的动作列表
        {
          "actionType": "toast", // 执行toast提示动作
          "args": { // 动作参数
            "msgType": "info",
            "msg": "派发点击事件"
          }
        }
      ]
    },
    "mouseenter": {{ // 监听鼠标移入事件
      "actions": [
        {
          "actionType": "toast",
          "args": {
            "msgType": "info",
            "msg": "派发鼠标移入事件"
          }
        }
      ]
    },
    "mouseleave": {{ // 监听鼠标移出事件
      "actions": [
        {
          "actionType": "toast",
          "args": {
            "msgType": "info",
            "msg": "派发鼠标移出事件"
          }
        }
      ]
    }
  }
}

上下文

执行动作时，可以通过${event.data}获取事件对象的数据、通过${__rendererData}获取组件当前数据域，例如：

运行日志

可以在浏览器控制台查看运行日志，类似如下

run action ajax
  [ajax] action args, data {api: {…}, messages: {…}}
  [ajax] action end event {context: {…}, type: 'click', prevented: false, stoped: false, preventDefault: ƒ, …}

代表运行了 ajax 动作，第二行是传递的参数和数据，第三行是执行完动作之后的 event 值，可以用做后续动作的参数。

分类

事件包含渲染器事件和广播事件。

• 渲染器事件，由具体的渲染器组件提供，每个渲染器组件暴露的事件可以查看具体的组件文档的事件表；
• 广播事件，即自定义事件，可以自定义派发的事件名称eventName，其他渲染器可以监听该自定义事件并配置响应动作。

动作包含通用动作、组件动作、广播动作、自定义动作，可以通过配置actionType来指定具体执行什么动作。

发送 http 请求

通过配置actionType: 'ajax'实现 http 请求发送，该动作需实现 env.fetcher 请求器。

静默模式

当配置silent: true时，请求完成后不会弹出提示信息。

可读取的数据

请求配置中可读取的数据包含事件源所在数据域和动作执行产生的数据。可以通过api.data配置数据映射来读取所需数据。例如：

• 取所在数据域的数据：通过"name": "${name}", "email": "${email}"来映射表单校验数据（只适用于事件源在表单内的情况）
• 取动作产生的数据：通过"name": "${event.data.validateResult.payload.name}", "email": "${event.data.validateResult.payload.email}"来映射表单校验数据，这种是获取前面表单校验动作的校验结果数据。通过"&": "${event.data.validateResult.payload}"展开表单校验数据，结果相同，这是一个数据映射小技巧

动作属性

其他属性

请求响应结果的结构如下：

{
  // 状态码
  "responseStatus": 0,
  // 响应数据
  "responseData": {
    "xxx": "xxx"
  },
  // 响应消息
  "responseMsg": "ok"
}

弹窗

打开弹窗（模态）

通过配置actionType: 'dialog'实现 Dialog 弹窗。

动作属性

关闭弹窗（模态）

通过配置actionType: 'closeDialog'实现关闭当前弹窗；附加配置componentId可以实现关闭指定弹窗。

其他属性

打开抽屉（模态）

通过配置actionType: 'drawer'实现 Drawer 抽屉打开。

动作属性

关闭抽屉（模态）

通过配置actionType: 'closeDrawer'实现关闭当前抽屉；附加配置componentId可以实现关闭指定抽屉。

其他属性

打开确认弹窗

通过配置actionType: 'confirmDialog'打开确认对话框。确认对话框弹出后，如果选择取消操作，将不会执行该动作后面的动作。如下面的例子，点击确认之后将弹出toast提示，点击取消则不会提示。

普通文本内容

动作需要实现 env.confirm: (msg: string, title?: string) => boolean | Promise<boolean>。

自定义弹窗内容

可以通过body像配置弹窗一样配置确认弹窗的内容。

动作属性

提示对话框

通过配置actionType: 'alert'打开提示对话框，该对话框只有确认按钮。该动作需要实现 env.alert: (msg: string) => void。

动作属性

toast 提示

通过配置actionType: 'toast'实现弹出 toast 提示，该动作需实现 env.notify(type: ToastLevel, msg: string, conf?: ToastConf) => void 方法。

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

跳转链接

通过配置actionType: 'url'或actionType: 'link'实现链接跳转，该动作需实现 env.jumpTo(to: string, action?: any) => void 方法。

打开页面

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

打开单页

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

浏览器

浏览器回退

1.8.0 及以上版本

通过配置actionType: 'goBack'实现页面回退。

前进/后退到指定页面

1.8.0 及以上版本

通过配置actionType: 'goPage'实现浏览器页面的前进/后退。只有当历史记录中存在目标页面时才会生效。

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

浏览器刷新

1.8.0 及以上版本

通过配置actionType: 'refresh'实现浏览器刷新。

复制

通过配置actionType: 'copy'和复制属性实现文本的复制操作，该动作需实现 env.copy(contents: string, options?: any) => void 方法。

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

打印

6.2.0 及以后版本

打印页面中的某个组件，对应的组件需要配置 id，如果要打印多个，可以使用 "ids": ["x", "y"] 来打印多个组件，只支持主要是容器类组件 crud、crud2、form、table、wrapper、container、flex、grid、grid2d、tableview

breaking：在 6.2.0 版本中配置是 testid，但这个配置会导致性能问题，所以新版使用 id 作为标识。

发送邮件

通过配置actionType: 'email'和邮件属性实现发送邮件操作。

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

更新事件上下文数据

6.3.0 及以上版本

修改 event.data 对象中的数据，修改后后续的动作中可以引用，及时生效，不像更新组件上下文数据是个异步操作。可以用来临时存储数据。

等待

6.3.0 及以上版本

通过配置actionType: 'wait'，等待指定时间（args.time 毫秒数）后执行后续动作。

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

自定义 JS

通过配置actionType: 'custom'实现自定义 JS。JS 中可以访问以下对象和方法：

• context，渲染器上下文
• doAction() 动作执行方法，用于调用任何 actionType 指定的动作
• event，事件对象，可以调用 setData()、stopPropagation()、preventDefault()分别实现事件上下文设置、动作干预、事件干预，可以通过 event.data 获取事件上下文

自定义函数签名： script:(context,doAction,event)=>{}

动作属性

支持异步

2.0.3 及以上版本

• 方式一：通过返回 Promise 实例的方式

• 方式二：通过返回 Thunk 的方式

存储数据

有时在执行自定义 JS 的时候，希望该过程中产生的数据可以分享给后面的动作使用，此时可以通过event.setData()来实现事件上下文的设置，这样后面动作都可以通过事件上下文来获取共享的数据。

注意：直接调用event.setData()将修改事件的原有上下文，如果不希望覆盖可以通过event.setData({...event.data, ...{xxx: xxx}})来进行数据的合并。

触发指定组件动作

通过配置componentId或componentName来触发指定组件的动作（不配置将调用当前组件自己的动作），组件动作配置通过args传入(> 1.9.0 及以上版本)，动作参数请查看对应的组件的动作表，更多示例请查看组件事件动作示例。

更新组件数据

1.8.0 及以上版本

更新数据即更新指定组件数据域中的数据（data），通过配置actionType: 'setValue'实现组件数据域变量更新，通过它可以实现组件间联动更新、数据回填，更多示例请查看更新数据示例。

注意事项

• 这个动作是异步的，所以不能直接通过${xxx}来获取更新后的数据，如果需要请更新事件上下文数据，然后通过${event.data.xxx}来获取。
• 数据类型支持范围：基础类型、对象类型、数组类型，数据类型取决于目标组件所需数据值类型
• 目标组件支持范围：form、dialog、drawer、wizard、service、page、app、chart，以及数据输入类组件
• < 2.3.2 及以下版本，虽然更新数据可以实现对组件数据域的更新，但如果更新数据动作的数据值来自前面的异步动作（例如 发送 http 请求、自定义 JS（异步）），则后面的动作只能通过事件变量${event.data.xxx}来获取异步动作产生的数据，无法通过当前数据域${xxx}直接获取更新后的数据。
• 它的值通常都是对象形式，比如 form 传递的值应该是类似 {"user": "amis"}，这时就会更新表单里的 user 字段值为 amis

刷新组件请求

通过配置actionType: 'reload'刷新指定组件的数据请求，支持数据容器类组件（form、wizard、service、page、app、chart、crud）以及支持动态数据的输入类组件，详见组件的动作表。更多示例请查看刷新示例。

刷新输入类组件

针对支持远程数据的输入类组件，支持刷新目标组件的数据请求。

刷新 CRUD

刷新 CRUD 时，如果配置了data，将发送data给目标 CRUD 组件，并将该数据合并到目标 CRUD 组件的数据域中，然后触发目标组件的刷新操作，即 CRUD 数据拉取接口将自动追加data参数到请求中，更多示例可以查看CRUD reload。

刷新其他数据容器类组件

刷新容器类组件（form、wizard、service、page、app、chart）时，如果配置了data，将发送data给目标组件，并将该数据合并到目标组件的数据域中。

获得刷新后的结果

6.9.0 及以上版本

通过配置 outputVar 可以拿到刷新后的结果，例如以下示例，点击按钮后，会串行按顺序刷新 service 1 和 service2， 同时 service2 可以拿到 service1 的返回值。

动作属性

其他属性

修改组件状态

1.8.0 及以上版本

通过配置actionType: 'show'或'hidden'或'enabled'或'disabled'或'static'或'nonstatic'实现对指定组件的显示、隐藏、启用、禁用，仅支持实现了对应状态控制功能的数据输入类组件。

显示与隐藏

启用与禁用

静态展示与编辑态

其他属性

执行目标组件的动作

例如，点击按钮后，切换选项卡。

触发广播

通过配置actionType: 'broadcast'实现触发一个广播。

动作属性（args）

< 2.3.2 及以下版本，以下属性与 args 同级。

其他属性

注册自定义动作

除了以上内置动作，你还可以注册自己的动作。通过对RendererAction的run方法的实现可以定制自己的动作逻辑，最后通过registerAction注册到 amis 事件动作中。

import {
  ListenerAction,
  ListenerContext,
  registerAction,
  RendererAction
} from 'amis-core';
import {RendererEvent} from 'amis-core';

// 动作定义
interface IMyAction extends ListenerAction {
  actionType: 'my-action';
  args: {
    param1: string, // 动作参数1
    param2: string // 动作参数2
  };
}

/**
 * 我的动作实现
 */
export class MyAction implements RendererAction {
  run(action: IMyAction, renderer: ListenerContext, event: RendererEvent<any>) {
    const props = renderer.props;
    const {param1, param2} = action.args;

    // 你的动作逻辑
    // ...
  }
}

// 注册自定义动作
registerAction('my-action', new MyAction());

编排动作

通过配置不同的逻辑动作实现动作编排，支持嵌套。

条件

通过配置expression: 表达式或ConditionBuilder组合条件来实现条件逻辑。

其他属性

循环

通过配置actionType: 'loop'实现循环逻辑。

单层循环

嵌套循环

动作属性（args）

< 1.8.0 及以下版本，以下属性与 args 同级。

其他属性

< 2.3.2 及以下版本，以下属性与 args 同级。

Break 动作

通过配置actionType: 'loop'和actionType: 'break'实现循环跳出。

Continue 动作

通过配置actionType: 'loop'和actionType: 'continue'实现循环跳过。

排他（switch）

通过配置actionType: 'switch'实现排他逻辑。

其他属性

并行

通过配置actionType: 'parallel'实现并行执逻辑。

其他属性

动作间数据传递

从事件触发开始，整个数据流包含事件本身产生的事件数据和动作产生的动作数据，事件源头产生的数据在 AMIS 事件动作机制底层已经自动加入渲染器数据域，可以通过xxx直接获取（< 2.3.2 及以下版本 为 event.data.xxx），而部分动作产生的数据如何流动需要交互设计者进行介入，对于数据流动可以通过数据映射，将上一个动作产生的数据作为动作参数写入下一个动作。

传递数据

通过 data 指定输入的参数数据（< 2.3.2 及以下版本通过args传递数据），它是一个键值对。

引用 http 请求返回的数据

http 请求动作执行结束后，后面的动作可以通过 ${responseResult}或${{outputVar}}来获取请求响应结果，响应结果的结构定义参考发送 http 请求。

< 2.3.2 及以下版本 需要通过 ${event.data.{xxx}}来获取以上信息，例如：${event.data.responseResult}

获取组件相关数据

可以通过表达式函数GETRENDERERDATA(id, path)和GETRENDERERPROP(id, path)分别获取指定组件的数据和属性。

该函数参数说明如下：

干预动作执行

事件动作干预是指执行完当前动作后，干预所监听事件默认处理逻辑和后续其他动作的执行。通过preventDefault、stopPropagation分别阻止监听事件默认行为和停止下一个动作执行。

阻止事件默认行为

有些组件内置了一些逻辑来帮助用户降低配置成本，但可能这些逻辑并不符合设计者的业务需求，这时可以通过onEvent来监听对应的事件，并通过preventDefault来阻止那些默认处理逻辑来达到想要的最终效果。更多示例请查看阻止组件默认行为示例。

6.3.0 版本开始支持

或者直接通过动作来阻止

{
  "actionType": "preventDefault",
  "expression": "${command === 'Do not close'}"
}

停止后续动作执行

通过onEvent可以对监听的事件配置一组动作，这些动作是顺序执行的，有时间设计者希望执行某个/些动作后就停止继续执行后面的动作，这时候可以通过stopPropagation来停止执行后面配置的所有动作。

6.3.0 版本开始支持

或者直接通过动作来跳过后续逻辑

{
  "actionType": "stopPropagation",
  "expression": "${command === 'Do not close'}"
}

忽略动作报错继续执行

3.3.1 及以上版本

默认情况下，尝试执行一个不存在的目标组件动作、JS 脚本执行错误等程序错误都会导致动作执行终止，可以通过ignoreError: true来忽略动作报错继续执行后面的动作。

自定义组件接入事件动作

需求场景主要是想要自定义组件的内部事件暴露出去，能够通过对事件的监听来执行所需动作，并希望自定义组件自身的动作能够被其他组件调用。接入方法是通过props.dispatchEvent派发自身的各种事件，使其具备更灵活的交互设计能力；通过实现doAction方法实现其他组件对其专属动作的调用，需要注意的是，此处依赖内部的 Scoped Context来实现自身的注册，可以参考 组件间通信。

属性表