sortables.md.svn-base

一款开源强大的javascript控件

Class: Sortables {#Sortables}
=============================

提供在列表自身或列表间拖放列表项的功能

### 参数:

1. list - (*mixed*) 必选项, 可拖放的一个或多个列表元素
 * 本参数可以是一个[Element][], 或一个[Elements][], 或是一个CSS选择器. 当只给出一个列表元素时, 则该元素只能在自身内部进行拖放.
 * 要在多个列表间进行拖放, 则请传入多个列表元素或一个能获得多个元素的CSS选择器. 参见下面的示例.
2. options - (*object*) 参见下列可选项和事件:

#### 可选项:

* constrain - (*boolean*: 默认为 false) 是否将元素的拖动范围限制在父容器中
* clone     - (*mixed*: 默认为 false)   是否拖动时创建拖动元素的影子元素. 或者也可以指定一个可返回某元素(作为影子元素)的function, 该function接收的参数依次为mousedown事件, 拖动项元素, 及列表元素.
* handle    - (*string*: 默认为 false)  指定可拖放项元素内部可拖动部位的CSS选择器. 如果选择器未能匹配任何元素, 则使用列表项自身作为可拖动部位.
* opacity   - (*integer*: 默认为 1)     占位元素的透明度
* revert    - (*mixed*: 默认为 false)   是否对拖放项使用滑动特效. 也可以传入一个object对象作为特效可选项.
* snap      - (*integer*: 默认为 4)     列表项对拖动的起始响应的像素量

### 事件:

* start    - 列表项开始拖动时触发
* sort     - 列表项被拖放到列表中其他位置时触发
* complete - 列表项拖动结束时触发

### 示例:

	//基于列表元素list-1创建一个Sortables实例,并指定了额外的revert特效
	var mySortables = new Sortables('list-1', {
		revert: { 
			duration: 500, 
			transition: 'elastic:out' 
		}
	});

	//创建一个可让list-1,list-2进行拖放的Sortables实例. 由于可选项constrain为true, 所以两个列表之间的项不能互相拖放
	var mySortables = new Sortables('#list-1, #list-2', {
		constrain: true,
		clone: false,
		revert: true
	});
	
	//创建一个可在list-1,list-2,list-3之间进行互相拖放的Sortables实例
	var mySortables = new Sortables('#list-1, #list-2, #list-3');



Sortables 方法: attach {#Sortables:attach}
--------------------------------------------

为可拖动元素添加鼠标监听, 使可进行拖放

### 语法:

	mySortables.attach();

### 返回值:

* (*object*) Sortables实例



Sortables 方法: detach {#Sortables:detach}
--------------------------------------------

删除可拖动元素的鼠标监听,使不能进行拖放

### 语法:

	mySortables.detach();

### 返回值:

* (*object*) Sortables实例



Sortables 方法: addItems {#Sortables:addItems}
------------------------------------------------

向Sortables实例中添加可拖放项

### 语法:

	mySortables.addItems(item1[, item2[, item3[, ...]]]);

### 参数:

1. items - (*mixed*) 单个或多个元素, 或是元素数组

### 返回值:

* (*object*) Sortables实例

### 示例:

	var mySortables = new Sortables('#list1, #list2');

	var element1 = new Element('div');
	var element2 = new Element('div');
	var element3 = new Element('div');

	$('list1').adopt(element1);
	$('list2').adopt(element2, element3);
	
	mySortables.addItems(element1, element2, element3);

### 备注:

- 由于一个Sortables实例可对应多个列表, 所以添加的列表项元素不会自动插入到列表元素上, 需要手动插入
- 操作顺序: 先向列表插入列表项元素, 然后调用addItems方法

### 另参考:

- [Sortables:removeItems](#Sortables:removeItems), [Sortables:addLists](#Sortables:addLists)



Sortables 方法: removeItems {#Sortables:removeItems}
------------------------------------------------------

从Sortables实例中删除可拖放项

### 语法:

	mySortables.removeItems(item1[, item2[, item3[, ...]]]);

### 参数:

1. items - (*mixed*) 单个或多个元素, 或是元素数组

### 返回值:

* (*Elements*) 被移除的列表项元素集合

### 示例:

	var mySortables = new Sortables('#list1, #list2');

	var element1 = $('list1').getFirst();
	var element2 = $('list2').getLast();

	mySortables.removeItems(element1, element2).destroy();

### 备注:

- 该方法并不会真正从DOM上删除元素, 仅仅是让这些元素失去拖放功能
- 正真删除列表项元素的操作顺序: 调用removeItems方法从Sortables实例中删除, 然后调用元素的destroy方法来从DOM上删除这些元素(如以上示例所示)

### 另参考:

- [Sortables:addItems](#Sortables:addItems), [Sortables:removeLists](#Sortables:removeLists)



Sortables 方法: addLists {#Sortables:addLists}
------------------------------------------------

向Sortables实例中增加一个或多个列表, 并允许新老列表之间进行互相拖放

### 语法:

	mySortables.addLists(list1[, list2[, list3[, ...]]]);

### 参数:

1. lists - (*mixed*) 可以是单个或多个元素, 或是元素数组

### 返回值:

* (*object*) Sortables实例

### 示例:

	var mySortables = new Sortables('list1');
	mySortables.addLists($('list2'));

### 备注:

- 本方法更复杂的用处是可用来进行单向拖放

### 另参考:

- [Sortables:removeLists](#Sortables:removeLists), [Sortables:addItems](#Sortables:addItems)



Sortables 方法: removeLists {#Sortables:removeLists}
------------------------------------------------------

从Sortables实例中删除一个或多个列表, 使得这些列表失去拖放功能

### 语法:

	mySortables.removeLists(list1[, list2[, list3[, ...]]]);

### 参数:

1. lists - (*mixed*) 单个或多个元素, 或是元素数组

### 返回值:

* (*Elements*) 被移除的列表元素集合

### 示例:

	var mySortables = new Sortables('#list1, #list2');
	mySortables.removeLists($('list2'));

### 另参考:

- [Sortables:addLists](#Sortables:addLists), [Sortables:removeItems](#Sortables:removeItems)



Sortables 方法: serialize {#Sortables:serialize}
--------------------------------------------------

获取排序列表中列表项的排列顺序.

### 参数:

1. index    - (*mixed*, 可选) 整数值或是布尔值false. 如果是整数值, 则代表要进行序列化输出的列表的索引号. 如果省略该参数, 或者为false, 则将对所有列表进行序列化输出.
2. modifier - (*function*, 可选) 用于覆盖默认输出内容的函数. 参见以下示例:

### 示例:

	mySortables.serialize(1); //返回第二个列表的序列化输出: ['item_1-1', 'item_1-2', 'item_1-3']

	mySortables.serialize();
	/*返回对所有列表的序列化输出:
	 * [
	 * 		['item_1-1', 'item_1-2', 'item_1-3'],
	 * 		['item_2-1', 'item_2-2', 'item_2-3'],
	 * 		['item_3-1', 'item_3-2', 'item_3-3']
	 * ]
	 */	

	mySortables.serialize(2, function(element, index){
		return element.getProperty('id').replace('item_','') + '=' + index;
	}).join('&');	
	
	//返回内容如: '3-0=0&3-1=1&3-2=2'



[Element]: /Elements/Element
[Elements]: /Element/Element/Element#Elements