Skip to main content
Version: 2.x

Events 事件

在 Storyboard 中可以为构件配置事件的处理：BrickConf。

例如：

brick: "your-brick"
events:
  something.happened:
    action: "console.warn"
  others.happened:
    - action: "console.log"
    - target: "other-brick"
      method: "openModal"

对于以上配置，在构件 <your-brick> 发起 something.happened 事件时，将触发内建处理函数 console.warn；而在发起 others.happened 事件时，将依次触发内建函数 console.log、找到 <other-brick> 并调用它的 openModal() 方法。

构件的事件处理器主要有三种：内建处理器、Provider 处理器、自定义构件处理器。

内建处理器​

使用 action: "..." 来配置内建处理器，使用 args: [...] 设置传递给处理器的参数。

当前内建处理器主要有以下几类：

内建处理器：history.*​

更多信息请参考 History 会话历史。

Action
history.push
history.replace
history.goBack
history.goForward
history.pushQuery
history.replaceQuery
history.pushAnchor
history.reload
history.block
history.unblock

内建处理器：location.*​

ActionArgumentsdescription
location.reload-浏览器刷新页面

内建处理器：window.*​

ActionArgumentsdescription
window.openurl: string, target: string打开页面（注意：需要自行按需补上 /next 的前缀）

内建处理器：legacy.*​

ActionArgumentsdescription
legacy.gourl: string通知 iframe 嵌套的老 console 跳转到指定页面地址

内建处理器：event.*​

ActionArgumentsdescription
event.preventDefault-阻止事件的默认行为

内建处理器：console.*​

ActionArgumentsdescription
console.logany-
console.errorany-
console.warnany-
console.infoany-

内建处理器：message.*​

ActionArgumentsdescription
message.successstring成功提示
message.errorstring失败提示
message.warnstring告警提示
message.infostring信息提示

内建处理器：handleHttpError​

ActionArgumentsdescription
handleHttpError-请求报错弹框提示

内建处理器：segue.*​

segue.* 接收一个必填参数和两个可选参数，分别为 Segue ID、路由中的 path 参数、URL Query 参数。

ActionArgumentsdescription
segue.pushsegueId: string, pathParams?: object, query?: object跳转到指定 Segue （新增会话记录）
segue.replacesegueId: string, pathParams?: object, query?: object跳转到指定 Segue （替换会话记录）

内建处理器：alias.*​

alias.* 接收一个必填参数和两个可选参数，分别为路由的 alias、路由中的 path 参数、URL Query 参数。

ActionArgumentsdescription
alias.pushalias: string, pathParams?: object, query?: object跳转到指定 alias 对应的路由（新增会话记录）
alias.replacealias: string, pathParams?: object, query?: object跳转到指定 alias 对应的路由（替换会话记录）

内建处理器：context.*​

context.* 接收两个参数：context name 和 context value。更多信息请参考 Context 上下文。注意：不能对绑定构件属性的 Context 执行 context.* 操作。

ActionArgumentsdescription
context.assignname: string, newValue: any使用 Object.assign() 更新已有的 Context 值
context.replacename: string, newValue: any使用新的值替换已有的 Context 值
context.loadname: string主动加载一个懒加载的 Context
context.refreshname: string强制更新一个异步的 Context

内建处理器：state.*​

state.* 接收两个参数：state name 和 state value。更多信息请参考 Template State 模板状态数据。

ActionArgumentsdescription
state.updatename: string, newValue: any使用新的值替换已有的 State 值
state.loadname: string主动加载一个懒加载的 State
state.refreshname: string强制更新一个异步的 State

内建处理器：localStorage.*​

localStorage 存储的信息，支持写入数据（setItem）方法和移除项（removeItem）方法。

需要获取数据的时候使用Evaluate Placeholders 求值占位符：<% LOCAL_STORAGE.getItem("your-key") %>

ActionArgumentsdescription
localStorage.setItemkey: string, value: any往 localStorage 中写入一项数据
localStorage.removeItemkey: string往 localStorage 中移除项

内建处理器：sessionStorage.*​

sessionStorage 存储的信息，支持写入数据（setItem）方法和移除项（removeItem）方法。

需要获取数据的时候使用Evaluate Placeholders 求值占位符：<% SESSION_STORAGE.getItem("your-key") %>

ActionArgumentsdescription
sessionStorage.setItemkey: string, value: any往 sessionStorage 中写入一项数据
sessionStorage.removeItemkey: string往 sessionStorage 中移除项

内建处理器：tpl.*​

tpl.dispatchEvent 可以用于在 Custom Template 自定义模板内部定义的 useBrick 中以 Custom Template 的名义对外发送事件。

它触发时将使用该构件所属的 Custom Template 作为事件源发送自定义事件，第一个参数为新的事件类型名，第二个参数是 CustomEventInit，可以包装新的 detail 数据。。

ActionArgumentsdescription
tpl.dispatchEventeventType: string, init: CustomEventInit使用构件所属的 Custom Template 作为事件源发送自定义事件

Provider 处理器​

使用 useProvider 指定要使用的 Provider 构件名，并通过 callback 来处理 Provider 的 resolve(...args) 调用后的结果。

Fieldtyperequireddefaultdescription
useProviderstring✔️-Provider 构件名
argsany[]--调用构件方法时传递的参数，不填则将原始事件本身作为唯一参数传入
callback{ success, error, finally, progress }--执行 Provider 构件的 resolve(...args) 后的异步回调，更多信息请参考 Provider 异步回调
pollProviderPollOptions--启用轮询模式，更多信息请参考 Provider 轮询

自定义构件处理器​

自定义构件处理器让构件的事件可以传递给其它指定构件，执行指定构件的方法或设置指定构件的属性。

自定义构件处理器：执行指定构件方法​

Fieldtyperequireddefaultdescription
targetstring✔️-接收事件的构件的 css selector
multiplebool-false是否查询多个构件（querySelectorAll），而不是单个构件（querySelector）
methodstring✔️-想要调用的构件的方法名
argsany[]-[event]调用构件方法时传递的参数，不填则将原始事件本身作为唯一参数传入
callback{ success, error, finally }--执行 method 后的异步回调，更多信息请参考 Provider 异步回调

自定义构件处理器：设置指定构件属性​

Fieldtyperequireddefaultdescription
targetstring✔️-接收事件的构件的 css selector
multiplebool-false是否查询多个构件（querySelectorAll），而不是单个构件（querySelector）
propertiesobject--想要设置模板构件的属性字典
injectDeepbool-false是否使用深度参数注入模板

提示：事件处理器的 args 参数可使用参数注入 💉。

条件判断 💉​

在事件处理器中可以配置 if 字段，以根据事件信息决定是否执行相关事件处理。它的使用方式和条件渲染大体相似，例如：

events:
  button.click:
    if: "<% EVENT.detail.length > 0 %>"
    action: history.push

接口定义​

请查看 BrickEventHandler

// `events` 为一个字典，*key* 为事件类型，*value* 为事件处理器或事件处理器的数组。
interface BrickEventsMap {
  // 配置为数组时表示多个有序处理器。
  [key: string]: BrickEventHandler | BrickEventHandler[];
}

变更历史​

组件版本变更
brick_next2.75.12context.load context.refresh state.load state.refresh 支持配置回调事件 callback
-2.75.9新增内建处理器 context.load context.refresh state.load state.refresh
-2.15.23新增内建处理器 localStorage.setItem localStorage.removeItem
-1.29.0内置事件处理器支持 history.block 和 history.unblock
-1.23.2新增 Provider 处理器
-1.23.2新增 Provider 处理器
-1.21.10新增内建处理器 alias.push alias.replace
-1.21.7新增内建处理器 tpl.dispatchEvent
-1.21.3新增内建处理器 context.assign context.replace
-1.16.17新增内建处理器 segue.push segue.replace
-1.15.20支持 Provider 异步回调：callback
-1.15.16新增内建处理器 history.pushAnchor