1Introduction
- description：DOM 事件
- author：ydr.me
- create：2016-04-12 15:04
- update：2018年04月04日15:46:34
- github：
https://github.com/blearjs/blear.core.event
2Example
var event = require('blear.core.event');
3Static
3.1.on(el, type, [sel], listener, [options]): undefined
冒泡模式的监听事件，支持代理。
你需要知道哪些事件不能代理监听的。
// 监听 div 的 click 事件
event.on(divEl, 'click', callback);
// 代理监听 div 下的 .btn 的 click 事件
event.on(divEl, 'click', '.btn', callback);
3.1.1el
- 类型：
HTMLElement
3.1.2type
- 类型：
String - 说明：多个事件类型用空格分开
3.1.3sel
- 类型：
String | HTMLElement - 说明：委托代理的元素或选择器
3.1.4listener
- 类型：
Function - 说明：事件监听函数
3.1.5options
- 类型：
Object - 说明：配置
3.1.6options.capture
- 类型：
boolean - 说明：是否捕获模式，为
true表示 listener 会在该类型的事件捕获阶段传播到该 EventTarget 时触发。 - 默认：
false
3.1.7options.passive
- 类型：
boolean - 说明：是否顺从模式，为
true表示 listener 永远不会调用 preventDefault()。如果 listener 仍然调用了这个函数，客户端将会忽略它并抛出一个控制台警告。 - 默认：
false
3.1.8options.once
- 类型：
boolean - 说明：是否单次（目前无效），为
true表示 listener 在添加之后最多只调用一次。如果是 true， listener 会在其被调用之后自动移除。 - 默认：
false
3.2.once(el, type, [sel], listener, [options]): undefined
冒泡模式的监听事件，支持代理。
只监听一次，触发后立即取消监听。
你需要知道哪些事件不能代理监听的。
// 监听 div 的 click 事件
event.once(divEl, 'click', callback);
// 代理监听 div 下的 .btn 的 click 事件
event.once(divEl, 'click', '.btn', callback);
3.2.1el
- 类型：
HTMLElement
3.2.2type
- 类型：
String - 说明：多个事件类型用空格分开
3.2.3sel
- 类型：
String | HTMLElement - 说明：委托代理的元素或选择器
3.2.4listener
- 类型：
Function - 说明：事件监听函数
3.2.5options
- 类型：
Object - 说明：配置
3.2.6options.capture
- 类型：
boolean - 说明：是否捕获模式，为
true表示 listener 会在该类型的事件捕获阶段传播到该 EventTarget 时触发。 - 默认：
false
3.2.7options.passive
- 类型：
boolean - 说明：是否顺从模式，为
true表示 listener 永远不会调用 preventDefault()。如果 listener 仍然调用了这个函数，客户端将会忽略它并抛出一个控制台警告。 - 默认：
false
3.2.8options.once
- 类型：
boolean - 说明：是否单次（目前无效），为
true表示 listener 在添加之后最多只调用一次。如果是 true， listener 会在其被调用之后自动移除。 - 默认：
false
3.3.un(el, type, listener): undefined
取消事件监听。
// 取消监听 div 的所有事件（必须由 event 监听的事件）
event.un(divEl);
// 取消监听 div 的所有 click 事件（必须由 event 监听的事件）
event.un(divEl, 'click');
// 取消监听 div 的一个 click 事件
event.un(divEl, 'click', callback);
3.3.1el
- 类型：
HTMLElement
3.3.2type
- 类型：
String - 说明：多个事件类型用空格分开，如果为空，则取消所有事件
- 默认：
null
3.3.3listener
- 类型：
Function - 说明：如果为空，则取消所有
type事件 - 默认：
null
3.4.length(el, [type]): length
获取 DOM 上绑定事件的数量。
3.4.1el
- 类型：
HTMLElement
3.4.2type
- 类型：
String - 说明：只支持一个事件类型，如果为空，则返回该元素上所有事件数量
- 默认：
null
3.4.3length
- 类型：
Number
3.5.create(type, [properties], [Constructor=Event]): event
创建一个自定义事件。
// 创建一个单击事件
var clickEv = event.create('click');
// 创建一个我的单击事件
var myClickEv = event.create('my-click');
// 创建一个我的单击事件
var myClickEv = event.create('my-click', MouseEvent);
3.5.1type
- 类型：
String - 说明：一个事件类型
3.5.2properties
- 类型：
Object - 说明：事件描述
3.5.3properties.bubbles
- 类型：
boolean - 说明：是否可以冒泡
- 默认：
true
3.5.4properties.cancelable
- 类型：
boolean - 说明：是否可以被组织冒泡
- 默认：
true
3.5.5properties.detail
- 类型：
Object - 说明：事情详情
- 默认：
Object
3.5.6event
- 类型：
Event - 说明：返回一个自定义事件
3.6.emit(el, ev): undefined
触发一个事件，遵循 DOM 事件的传播规则。
// 触发一个单击事件
event.emit(btnEl, clickEv);
// 触发一个我的单击事件
event.emit(btnEl, myClickEv);
3.6.1el
- 类型：
HTMLElement - 说明：元素
3.6.2ev
- 类型：
Event - 说明：事件
3.7.clone(ev1, [type]): ev2
克隆并返回一个新事件对象。
3.7.1clone: ev1
- 类型：
Event - 说明：原始事件
3.7.2clone: type
- 类型：
Event - 说明：新的事件类型，默认取原来的事件类型
3.7.3clone: ev2
- 类型：
Event - 说明：克隆后的事件
3.8.special(displayType, originalType, hanle)
指定一个特殊事件处理，比如用mouseover实现代理级别的mouseenter。
event.special('mouseenter', 'mouseover', function (ev, listener) {
var target = this;
var related = ev.relatedTarget;
// For mouseenter/leave call the handler if related is outside the target.
// NB: No relatedTarget if the mouse left/entered the browser window
if (!related || (related !== target && !selector.contains(related, target))) {
listener.call(target, clone(ev, displayType));
}
});
3.8.1displayType
- 类型：
String - 说明：事件显示名称
3.8.2originalType
- 类型：
String - 说明：事件原始名称
3.8.3hanle
- 类型：
Function - 说明：事件条件满足后处理
4Dependencies
- blear.utils.access
- blear.utils.typeis
- blear.utils.object
- blear.utils.random
- blear.utils.array
- blear.core.selector
5Reference
- DOM 事件详解：
yujiangshui.com
- DOM 事件维基百科：
en.wikipedia.org