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