element.event.md

一款开源强大的javascript控件

Native: Element {#Element}
==========================
对Element的进行事件处理的方法

以下提供的方法对window和document同样有效

### 备注:
- 在Internet Explorer下, 如果不是使用[Element:fireEvent](#Element:fireEvent)方法触发元素的事件的话, 则事件监听器的执行顺序是随机的


Element 方法: addEvent {#Element:addEvent}
--------------------------------------------

向DOM元素添加一个事件监听器

###	语法:

	myElement.addEvent(type, fn);

###	参数:

1. type - (*string*)  监听的事件类型 ('click', 'load', 等等), 注意没有前缀'on'
2. fn   - (*funtion*) 监听函数

###	返回值:

* (*element*) 主调元素

### 示例:

##### HTML:

	<div id="myElement">Click me.</div>

##### JavaScript

	$('myElement').addEvent('click', function(){
		alert('clicked!');
	});

### 备注:

- 可以在监听函数中使用返回false的手段或者调用[Event:stop](#Event:stop)来停止事件
- 在Document和Window上也具有本方法

###	另参考:

- [w3schools Event Attributes](http://www.w3schools.com/html/html_eventattributes.asp)



Element 方法: removeEvent {#Element:removeEvent}
--------------------------------------------------

删除指定的事件监听函数

###	语法:

	myElement.removeEvent(type, fn);

###	参数:

1. type - (*string*)  事件名
2. fn   - (*funtion*) 要删除的函数

###	返回值:

* (*element*) 主调元素

###	示例:

#### 独立使用:

	//先添加一个监听器
	var destroy = function(){ 
		alert('Boom: ' + this.id); 
	};
	$('myElement').addEvent('click', destroy);
	
	//之后,删除它
	$('myElement').removeEvent('click', destroy);


#### 和bind配合使用:

	var destroy = function(){ 
		alert('Boom: ' + this.id); 
	}
	var boundDestroy = destroy.bind($('anotherElement'));
	$('myElement').addEvent('click', boundDestroy);
	
	//之后,删除它
	
	//1.这里将不会删除任何监听器(因为元素上并不存在这个监听器)
	$('myElement').removeEvent('click', destroy);
	
	//2.这里也不会删除任何监听器(因为这里其实创建了一个新的函数,和元素上的监听器不是相同的引用)
	$('myElement').removeEvent('click', destroy.bind($('anotherElement')); 
	
	//3.可以正确删除监听器
	$('myElement').removeEvent('click', boundDestroy);

###	备注:

- 当使用[Function:bind][] 或 [Function:pass][] 等创建函数时, 将创建一个新的引用. 如果要正确使用removeEvent来删除监听器, 你必须传入原先监听器的引用
- 在Document和Window上也具有本方法



Element 方法: addEvents {#Element:addEvents}
----------------------------------------------

向DOM元素一次添加多个事件监听器


###	语法:

	myElement.addEvents(events);

###	参数:

1. events - (*object*) 键值对对象: 键为事件名, 值为监听函数

###	返回值:

* (*element*) 主调元素

###	示例:

	$('myElement').addEvents({
		'mouseover': function(){
			alert('mouseover');
		},
		'click': function(){
			alert('click');
		}
	});

###	备注:

- 在Document和Window上也具有本方法

###	另参考:

- [Element:addEvent](#Element:addEvent)



Element 方法: removeEvents {#Element:removeEvents}
----------------------------------------------------

删除指定事件类型上的所有监听函数. 

如果未传入任何参数,则删除所有类型上的所有监听函数.

###	语法:

	myElements.removeEvents([type]);

###	参数:

1. type - (*string*, 可选) 事件名(如: 'click'). 如果未指定, 则删除所有事件

###	返回值:

* (*element*) 主调元素

###	示例:

	var myElement = $('myElement');
	myElement.addEvents({
		'mouseover': function(){
			alert('mouseover');
		},
		'click': function(){
			alert('click');
		}
	});

	myElement.addEvent('click': function(){ alert('clicked again'); });
	myElement.addEvent('click': function(){ alert('clicked and again :('); });
	myElement.removeEvents('click');

###	备注:

- 在Document和Window上也具有本方法

###	另参考:

- [Element:removeEvent](#Element:removeEvent)

Element 方法: fireEvent {#Element:fireEvent}
----------------------------------------------

触发元素上指定的事件类型

###	语法:

	myElement.fireEvent(type[, args[, delay]]);

###	参数:

1. type  - (*string*) 事件名(如: 'click')
2. args  - (*mixed*, 可选) 传递给监听函数的参数. 如果参数个数大于一,则必须使用数组
3. delay - (*number*, 可选) 延迟执行监听函数的毫秒数

###	返回值:

* (*element*) 主调元素

###	示例:
	//触发myElement的click事件,并在一秒钟后执行事件的监听函数(向每个函数传入anElement元素作为参数)
	$('myElement').fireEvent('click', $('anElement'), 1000);

###	备注:

- 本方法不会触发DOM级别的事件(如元素标签上内联方式的事件声明: onmousedown="...")
- 在Document和Window上也具有本方法


Element 方法: cloneEvents {#Element:cloneEvents}
--------------------------------------------------

复制目标元素上的所有事件到本元素

###	语法:

	myElement.cloneEvents(from[, type]);

###	参数:

1. from - (*element*) 目标元素
2. type - (*string*, 可选) 复制的事件类型. 如果为null或未指定,则复制所有的事件

###	返回值:

* (*element*) 主调元素

###	示例:

	var myElement = $('myElement');
	var myClone = myElement.clone().cloneEvents(myElement); //复制元素并复制下所有的事件

###	备注:

- 在Document和Window上也具有本方法


Hash: Element.Events{#Element-Events}
==============================================

用于创建自定义的事件类型

### 参数:

自定义一个事件时, Element.Events.yourproperty中可包含如下内容:

1. base - (*string*, 可选) 自定义事件所监听的基类事件. 如果指定了下面condition参数,则本参数必须填写
2. condition - (*function*, 可选) 自定义事件触发的条件函数 (函数的参数为一个Event实例)
3. onAdd - (*function*, 可选) 当元素添加自定义事件时触发的函数 (函数的参数为一个Event实例)
4. onRemove - (*function*, 可选) 当元素删除自定义事件时触发的函数 (函数的参数为一个Event实例)

### 示例:

	//自定义事件shiftclick: 按住shift后鼠标进行点击
	
	Element.Events.shiftclick = {
		base: 'click', //设置基类事件为click
		condition: function(event){ //用来检测其他事件触发条件
			return (event.shift == true); //检查是否按了shift键
		}
	};

	$('myInput').addEvent('shiftclick', function(event){
		log('the user clicked the left mouse button while holding the shift key');
	});

### 备注:

- 有以下几种不同类型的自定义事件组合:

 1. 只定义了base: 仅仅是重定向到基类事件上去
 2. 定义了base和condition: 重定向到基类事件上去,但由condition来决定是否触发
 3. 定义了onAdd和/或onRemove,并且定义了base和condition: 事件添加/删除时会触发关联的函数

### 警告:

请慎用自定义事件和原生事件同名,并使用condition选项(除非你打算覆盖原生事件).
(严重不推荐: 只有当你确切的明白你在做的事情时使用)


事件: mouseenter {#Element-Events:mouseenter}
-------------------------------------------------
(框架提供的自定义事件)

本事件在鼠标进入指定元素区域时触发,并且不会在鼠标穿越子元素的时候再次触发(区别于mouseover)


#### 示例:

	$('myElement').addEvent('mouseenter', myFunction);

#### 另参考:

- [Element:addEvent](#Element:addEvent)

事件: mouseleave {#Element-Events:mouseleave}
-------------------------------------------------
(框架提供的自定义事件)

本事件在鼠标离开指定元素区域时触发,并且不会再离开本元素的子元素的时候触发(区别于mouseout)

#### 示例:

	$('myElement').addEvent('mouseleave', myFunction);

#### 另参考:

- [Element:addEvent](#Element:addEvent)

事件: mousewheel {#Element-Events:mousewheel}
-------------------------------------------------
(框架提供的自定义事件)

本事件在鼠标滚轮滚动时触发

#### 示例:

	$('myElement').addEvent('mousewheel', myFunction);

#### 另参考:

- [Element:addEvent](#Element:addEvent)



[$]: /Element/#dollar
[Function]: /Native/Function
[Function:bind]: /Native/Function/#Function:bind
[Function:pass]: /Native/Function/#Function:pass
[Function:delay]: /Native/Function/#Function:delay
[Element.Events]: #Element-Events