element.md.svn-base

mooltools源码很不错的源码

Native: Window {#Window}
========================

下面一系列方法都是全局方法(Window上的方法)

函数: $ {#dollar}
---------------------

$方法有两个目的: 

 1.按id来获取元素 

 2.让Internet Explorer下所有元素获得[Element][]所提供的扩展方法

### 语法:

	var myElement = $(el);

### 参数:

1. el - (*mixed*) DOM元素的id或DOM元素的引用

### 返回值:

* (*mixed*) 如果取得指定的DOM元素,则返回该元素; 否则返回null

### 示例:

#### 通过id来获取DOM元素:

	var myElement = $('myElement');

#### 通过引用来获取DOM元素:

	var div = document.getElementById('myElement');  //普通的标准DOM元素
	div = $(div); 									 //经过扩展后的DOM元素

### 备注:

- 本方法在当不清楚到底是对实际的元素节点还是元素的id进行操作的时候比较有用.它还可以被认为是加强版的document.getElementById()
- 在Internet Explorer浏览器中, 当$第一次调用的时候,元素将进行对[Element][]的扩展, 将获得[Element][]中提供的方法
- 对原生HTMLElement支持的浏览器(诸如Safari, Firefox, 以及 Opera), 将自动获得[Element][]对DOM元素的扩展
- MooTools会检测一个元素是否需要被扩展, 所以$方法针对一个元素多次调用的话不会产生副作用



函数: $$ {#dollars}
-----------------------

获取并扩展一组DOM元素. 

获取到的元素数组中的每个元素都获得了[Element][]中的方法

### 语法:

	var myElements = $$(aTag[, anElement[, Elements[, ...]);

### 参数:

* 接受任意个数的参数, 参数类型如下: HTMLCollections, 元素数组, 多个单独的元素, 或者CSS选择器字符串

### 返回值:

* (array) - 符合条件的元素数组, 元素都经过[$][]的扩展

### 示例:

#### 由标签名获取元素:

	$$('a'); 		//获取页面中所有的<a>超链接元素
	$$('a', 'b'); 	//获取页面中所有的<a>超链接元素和粗体字元素

#### 使用CSS选择器(当[Selectors][]模块包含在源代码中时):

	$$('#myElement'); 			//返回一个数组,数组中只有一个id为'myElement'的元素
	$$('#myElement a.myClass'); //返回id为'myElement'的元素下的所有class为'myClass'的超链接元素

#### 更复杂的 $$ 用法:

	$$(myelement1, myelement2, 'a', '#myid, #myid2, #myid3', document.getElementsByTagName('div'));

### 备注:

- 当[Selectors][]模块加载后, [$$][] 可以接受功能丰富的CSS选择器. 否则,只支持最小程度的以元素标签名进行选择
- 如果未找到任何符合条件的元素, 则返回一个空数组
- [$$][]返回的总是一个数组, 不管符合的结果元素个数是多少

### 另参考:

- 查看[Selectors][]部分的文档



Native: Element {#Element}
==========================

本框架自定义的原生类, 用于提供对所有DOM元素进行功能扩展


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

根据指定的元素类型创建新元素

### 语法:

	var myEl = new Element(element[, properties]);

### 参数:

1. element - (*mixed*) 创建的Element对象的实际DOM元素的标签名
2. properties - (*object*, 可选) 元素的其他属性

### 返回值:

* (*element*) 一个新的MooTools扩展后的HTML元素

### 示例:

	var myAnchor = new Element('a', {
		'href': 'http://mootools.net',
		'class': 'myClass',
		'html': 'Click me!',
		'styles': {
			'display': 'block',
			'border': '1px solid black'
		},
		'events': {
			'click': function(){
				alert('clicked');
			},
			'mouseover': function(){
				alert('mouseovered');
			}
		}
	});

### 另参考:

- [$][], [Element:set][]



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

获取本元素下的第一个指定标签名的子元素. 

如果使用了[Selectors][],则可以使用CSS选择器.

### 语法:

	var myElement = myElement.getElement(tag);

### 参数:

1. tag - (*string*) 要查找的元素标签名

### 返回值:

* (*mixed*) 如果找到符合的子元素,则返回该子元素;否则返回null

### 示例:

	var firstDiv = $(document.body).getElement('div');

### 备注:

- Document类的实例上也有相应的本方法
- 当使用了[Selectors][]后,本方法将被使用CSS选择器的新方法替代
- [Selectors][] 可对 [Element:getElements][] 进行功能加强, 使用后可基于CSS选择器进行元素查找

### 另参考:

- 查看[Selectors][]部分的文档



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

获取本元素下所有指定标签名的子元素.

如果使用了[Selectors][],则可以使用CSS选择器.

### 语法:

	var myElements = myElement.getElements(tag);

### 参数:

1. tag - (*string*) 要查找的元素标签名

### 返回值:

* (*array*) 一个包含找到的元素数组([Elements][])

### 示例:

	var allAnchors = $(document.body).getElements('a');

### 备注:

- Document类的实例上也有相应的本方法
- 当使用了[Selectors][]后,本方法将被使用CSS选择器的新方法替代
- [Selectors][] 可以对 [Element:getElements][] 进行功能加强, 使用后可基于CSS选择器进行元素查找

### 另参考:

- 查看[Selectors][]部分的文档



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

获取本元素下指定id的子元素

### 语法:

	var myElement = anElement.getElementById(id);

### 参数:

1. id - (*string*) 子元素id

### 返回值:

* (*mixed*) 如果找到符合条件的子元素,则返回该子元素; 否则返回null

### 示例:

	var myChild = $('myParent').getElementById('myChild');

### 备注:

- 本方法不会覆盖掉Document实例原生的document.getElementById, Document实例的该方法还是原生方法



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

用于设置元素的属性值. 

这是一个'动态参数'方法. 传入的参数可以是任意在[Element.Properties][]中定义过类型.

### 语法:

	myElement.set(arguments);

### 参数:

- 两个参数的形式: (property, value)
	1. property - (*string*) 任意在[Element.Properties][]中定义过的属性名
	2. value - (*mixed*) 属性值
	
- 一个参数的形式: (properties)
	1. properties - (*object*) 多个属性组成的键值对对象

### 返回值:

* (*element*) 主调元素

### 示例:

#### 使用'属性-值':

	$('myElement').set('text', 'text goes here');
	$('myElement').set('class', 'active');
	
	//'styles'属性设置的对象值会进一步传递给Element:setStyles方法
	var body = $(document.body).set('styles', { 
		'font': '12px Arial',
		'color': 'blue'
	});

#### 使用属性键值对对象:

	var myElement = $('myElement').set({
		//'styles'属性设置的对象值会进一步传递给Element:setStyles方法
		'styles': {
			'font': '12px Arial',
			'color': 'blue',
			'border': '1px solid #f00'
		},
		//'events'属性设置的对象之会进一步传递给Element:addEvents方法
		'events': {
			'click': function(){ alert('click'); },
			'mouseover': function(){ this.addClass('over') }
		},
		//其他设置的属性值会传递给Element:setProperty方法
		'id': 'documentBody'
	});

### 备注:

- 所有属性参数都将传递给[Element.Properties][]中定义的对应的属性中的方法
- 如果在[Element.Properties][]未找到对应的属性, 则会使用[Element:setProperty][]方法

### 另参考:

- [Element][], [Element.Properties][], [Element:setProperty][], [Element:addEvents][], [Element:setStyles][]



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

用于获取元素的属性值. 

这是一个'动态参数'方法. 传入的参数可以是任意在[Element.Properties][]中定义过类型.

### 语法:

	myElement.get(property);

### 参数:

1. property - (*string*) 任意在[Element.Properties][]中定义过的属性名

### 返回值:

* (*mixed*) 调用[Element.Properties][]中对应属性下的get方法后的返回值

### 示例:

#### 获取自定义的属性:

	var tag = $('myDiv').get('tag'); //返回 "div".

#### 获取原生属性:

	var id = $('myDiv').get('id'); 			//返回 "myDiv".
	var value = $('myInput').get('value'); 	//返回 myInput元素的value属性值(myInput为input元素,具有原生value属性).

### 备注:

-  如果要获取的属性在[Element.Properties][]中未定义, 则会使用[Element:getProperty][]

### 另参考:

- [Element][], [Element.Properties][], [Element:getProperty][]



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

用于删除元素的属性值. 

这是一个'动态参数'方法. 传入的参数可以是任意在[Element.Properties][]中定义过类型.

### 语法:

	myElement.erase(property);

### 参数:

1. property - (*string*) 任意在[Element.Properties][]中定义过的属性名

### 返回值:

* (*mixed*) 调用[Element.Properties][]中对应属性下的erase方法后的返回值

### 示例:

	$('myDiv').erase('id'); 	//删除myDiv上的id
	$('myDiv').erase('class'); 	//删除myDiv上的class属性

### 备注:

-  如果要删除的属性在[Element.Properties][]中未定义, 则会使用[Element:removeProperty][]

### 另参考:

- [Element][], [Element.Properties][], [Element:removeProperty][]



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

检测元素的标签名是否为指定的标签名.

如果使用了[Selectors][],则可以使用CSS选择器.

### 语法:

	myElement.match(tag);

### 参数:

1. tag - (*string*) 标签名

### 返回值:

* (*boolean*) 如果元素符合给出的标签名,则返回true; 否则返回false

### 示例:

	$('myDiv').match('div'); //如果myDiv是一个div元素,则返回true

### 备注:

- 参见[Element:match](/Selectors/Selectors#Element:match).
- 当使用了[Selectors][]后,本方法会被功能更强的方法覆盖



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

向指定元素的指定位置中插入本元素

### 语法:

	myElement.inject(el[, where]);

### 参数:

1. el	- (*mixed*) 目标元素的id或引用
2. where - (*string*, 可选: 默认为'bottom') 插入的位置.  可为: 'top', 'bottom', 'after', 'before'

### 返回值:

* (*element*) 主调元素

### 示例:

##### JavaScript

	var myFirstElement  = new Element('div', {id: 'myFirstElement'});
	var mySecondElement = new Element('div', {id: 'mySecondElement'});
	var myThirdElement  = new Element('div', {id: 'myThirdElement'});

##### 结果 HTML

	<div id="myFirstElement"></div>
	<div id="mySecondElement"></div>
	<div id="myThirdElement"></div>

#### 插入到内部的底部(bottom):

##### JavaScript

	myFirstElement.inject(mySecondElement);

##### 结果 HTML

	<div id="mySecondElement">
		<div id="myFirstElement"></div>
	</div>

#### 插入到内部的顶部(top):

##### JavaScript

	myThirdElement.inject(mySecondElement, 'top');

##### 结果 HTML

	<div id="mySecondElement">
		<div id="myThirdElement"></div>
		<div id="myFirstElement"></div>
	</div>

#### 插入到之前(before):

##### JavaScript

	myFirstElement.inject(mySecondElement, 'before');

##### 结果 HTML

	<div id="myFirstElement"></div>
	<div id="mySecondElement"></div>

#### 插入到之后(after):

##### JavaScript

	myFirstElement.inject(mySecondElement, 'after');

##### 结果 HTML

	<div id="mySecondElement"></div>
	<div id="myFirstElement"></div>

### 另参考:

[Element:adopt](#Element:adopt), [Element:grab](#Element:grab), [Element:wraps](#Element:wraps)



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

向本元素内部的指定位置添加子元素

和[Element:inject](#Element:inject)相反的功能.



### 语法:

	myElement.grab(el[, where]);

### 参数:

1. el - (*mixed*) 目标元素的id或引用
2. where - (*string*, 可选: 默认为'bottom') 添加元素的位置.可为:'top' 或 'bottom'

### 返回值:

* (*element*) 主调元素

### 示例:

##### JavaScript

	var myFirstElement = new Element('div', {id: 'myFirstElement'});
	var mySecondElement = new Element('div', {id: 'mySecondElement'});

	myFirstElement.grab(mySecondElement);

##### 结果 HTML

	<div id="myFirstElement">
		<div id="mySecondElement"></div>
	</div>

### 另参考:

[Element:adopt](#Element:adopt), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)



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

向本元素内部添加子元素

功能和[Element:grab](#Element:grab)相同, 不过一次可以插入多个元素.


### 语法:
	
	myParent.adopt(el[, others]);
	
### 参数:

1. el - (*mixed*)          可为: 元素的id, 元素实例, 或元素数组
2. others - (*mixed*, 可选) 逗号分隔的多个元素,或是一个包含多个元素的数组

### 返回值:

* (*element*) 主调元素

### 示例:

##### JavaScript

	var myFirstElement  = new Element('div', {id: 'myFirstElement'});
	var mySecondElement = new Element('a', {id: 'mySecondElement'});
	var myThirdElement  = new Element('ul', {id: 'myThirdElement'});
	
	myParent.adopt(myFirstElement);
	myParent2.adopt(myFirstElement, 'mySecondElement');
	myParent3.adopt([myFirstElement, mySecondElement, myThirdElement]);

##### 结果 HTML

	<div id="myParent">
		<div id="myFirstElement" />
	</div>
	<div id="myParent2">
		<div id="myFirstElement" />
		<a />
	</div>
	<div id="myParent3">
		<div id="myFirstElement" />
		<a />
		<ul />
	</div>