# Selectable Widget
Categories: [Interactions](http://www.css88.com/jquery-ui-api/category/interactions/ "View all posts in Interactions")
## version added: 1.0
**Description:** 使用鼠標選擇一個或一組元素。
## QuickNav[Examples](#entry-examples)
### Options
+ [appendTo](#option-appendTo)
+ [autoRefresh](#option-autoRefresh)
+ [cancel](#option-cancel)
+ [delay](#option-delay)
+ [disabled](#option-disabled)
+ [distance](#option-distance)
+ [filter](#option-filter)
+ [tolerance](#option-tolerance)
### Methods
+ [destroy](#method-destroy)
+ [disable](#method-disable)
+ [enable](#method-enable)
+ [option](#method-option)
+ [refresh](#method-refresh)
+ [widget](#method-widget)
### Events
+ [create](#event-create)
+ [selected](#event-selected)
+ [selecting](#event-selecting)
+ [start](#event-start)
+ [stop](#event-stop)
+ [unselected](#event-unselected)
+ [unselecting](#event-unselecting)jQuery UI Selectable 插件允許一個元素被鼠標劃出的選擇區域選中. 同樣, 元素也可以被點擊選中或者同時按住 Ctrl/Meta鍵, 允許多個(非連續)的選擇.
### 依賴關系
* [UI Core](/category/ui-core/)
* [Widget Factory](/jQuery.widget/)
* [Mouse Interaction](/mouse/)
### 其他注意事項:
* 這個widget需要一些功能性的CSS,否則將無法正常工作。 如果你建立一個自定義的主題,使用widget指定的CSS文件作為一個激活點。
## Options
### appendTo**Type:** [Selector](http://api.jquery.com/Types/#Selector)
**Default:** `"body"`選擇幫手(套索) 應追加到哪個元素 。**Code examples:**
使用指定的 `appendTo` 參數初始化selectable :
```
$( ".selector" ).selectable({ appendTo: "#someElem" });
```
在初始化后設置或者獲取 `appendTo` 選項 :
```
// getter
var appendTo = $( ".selector" ).selectable( "option", "appendTo" );
// setter
$( ".selector" ).selectable( "option", "appendTo", "#someElem" );
```
### autoRefresh**Type:** [Boolean](http://api.jquery.com/Types/#Boolean)
**Default:** `true`這個選項確定每個選擇操作開始時如何刷新(重新計算)每個選擇項的位置和大小. 如果你有很多很多選擇項, 你應當設置此項為false并且手動調用[`refresh()`](#method-refresh) 方法.**Code examples:**
使用指定的 `autoRefresh` 參數初始化selectable :
```
$( ".selector" ).selectable({ autoRefresh: false });
```
在初始化后設置或者獲取 `autoRefresh` 選項 :
```
// getter
var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );
// setter
$( ".selector" ).selectable( "option", "autoRefresh", false );
```
### cancel**Type:** [Selector](http://api.jquery.com/Types/#Selector)
**Default:** `"input,textarea,button,select,option"`如果你使用了匹配選擇器,符合匹配的元素將被禁止可選.**Code examples:**
使用指定的 `cancel` 參數初始化selectable :
```
$( ".selector" ).selectable({ cancel: "a,.cancel" });
```
在初始化后設置或者獲取 `cancel` 選項 :
```
// getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );
// setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );
```
### delay**Type:** [Integer](http://api.jquery.com/Types/#Integer)
**Default:** `0`定義需要經過多少毫秒后選擇才會開始. 這可以預防意外的點擊造成元素被選擇.**Code examples:**
使用指定的 `delay` 參數初始化selectable :
```
$( ".selector" ).selectable({ delay: 150 });
```
在初始化后設置或者獲取 `delay` 選項 :
```
// getter
var delay = $( ".selector" ).selectable( "option", "delay" );
// setter
$( ".selector" ).selectable( "option", "delay", 150 );
```
### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean)
**Default:** `false`如果設置為 `true` 將禁止selectable。**Code examples:**
使用指定的 `disabled` 參數初始化selectable :
```
$( ".selector" ).selectable({ disabled: true });
```
在初始化后設置或者獲取 `disabled` 選項 :
```
// getter
var disabled = $( ".selector" ).selectable( "option", "disabled" );
// setter
$( ".selector" ).selectable( "option", "disabled", true );
```
### distance**Type:** [Number](http://api.jquery.com/Types/#Number)
**Default:** `0`定義需要移動多少個像素選擇才會開始. 如果指定了該項, 選擇不會馬上開始,而是會在鼠標移動了指定像素的距離之后才會開始.**Code examples:**
使用指定的 `distance` 參數初始化selectable :
```
$( ".selector" ).selectable({ distance: 30 });
```
在初始化后設置或者獲取 `distance` 選項 :
```
// getter
var distance = $( ".selector" ).selectable( "option", "distance" );
// setter
$( ".selector" ).selectable( "option", "distance", 30 );
```
### filter**Type:** [Selector](http://api.jquery.com/Types/#Selector)
**Default:** `"*"`匹配子元素中那些符合條件的元素才可以被選擇.**Code examples:**
使用指定的 `filter` 參數初始化selectable :
```
$( ".selector" ).selectable({ filter: "li" });
```
在初始化后設置或者獲取 `filter` 選項 :
```
// getter
var filter = $( ".selector" ).selectable( "option", "filter" );
// setter
$( ".selector" ).selectable( "option", "filter", "li" );
```
### tolerance**Type:** [String](http://api.jquery.com/Types/#String)
**Default:** `"touch"`指定那種模式,用來測試套索是否應該選擇一個項目。允許使用的值:
* `"fit"`: 套索完全重疊的項目。
* `"touch"`: 套索重疊的項目任何部分。
**Code examples:**
使用指定的 `tolerance` 參數初始化selectable :
```
$( ".selector" ).selectable({ tolerance: "fit" });
```
在初始化后設置或者獲取 `tolerance` 選項 :
```
// getter
var tolerance = $( ".selector" ).selectable( "option", "tolerance" );
// setter
$( ".selector" ).selectable( "option", "tolerance", "fit" );
```
## Methods
### destroy()
完全移除selectable功能. 這將使元素返回到之前的初始化狀態.
* 這個方法不接受任何參數。
**Code examples:**
調用 destroy 方法:
```
$( ".selector" ).selectable( "destroy" );
```
### disable()
禁用selectable.
* 這個方法不接受任何參數。
**Code examples:**
調用 disable 方法:
```
$( ".selector" ).selectable( "disable" );
```
### enable()
啟用 selectable.
* 這個方法不接受任何參數。
**Code examples:**
調用 enable 方法:
```
$( ".selector" ).selectable( "enable" );
```
### option( optionName )Returns: [Object](http://api.jquery.com/Types/#Object)
通過指定的`optionName`,獲取當前關聯的值。
* **optionName**Type: [String](http://api.jquery.com/Types/#String)要獲取值的選項名
**Code examples:**
調用 方法:
```
var isDisabled = $( ".selector" ).selectable( "option", "disabled" );
```
### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject)
獲取一個對象,它包含表示當前resizable的選項hash的鍵/值對。
* 這個方法不接受任何參數。
**Code examples:**
調用這個方法:
```
var options = $( ".selector" ).selectable( "option" );
```
### option( optionName, value )
通過指定的`optionName`,設置selectable的相關選項值。
* **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置值的選項名。
* **value**Type: [Object](http://api.jquery.com/Types/#Object)要設置選項的值。
**Code examples:**
調用這個方法:
```
$( ".selector" ).selectable( "option", "disabled", true );
```
### option( options )
為selectable設置一個或多個選項。
* **options**Type: [Object](http://api.jquery.com/Types/#Object)用來設置的選項/值對的對象。
**Code examples:**
調用這個方法:
```
$( ".selector" ).selectable( "option", { disabled: true } );
```
### refresh()
刷新每個選擇項的位置和大小. 這個方法用來手動重新計算選擇項的位置和大小,在[`autoRefresh`](#option-autoRefresh)設置為`false`時很有用。
* 這個方法不接受任何參數。
**Code examples:**
調用 refresh 方法:
```
$( ".selector" ).selectable( "refresh" );
```
### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery)
返回一個`jQuery`,它包含了selectable元素。
* 這個方法不接受任何參數。
**Code examples:**
調用 widget 方法:
```
var widget = $( ".selector" ).selectable( "widget" );
```
## Events
### create( event, ui )Type: `selectablecreate`
此事件會在 selectable 創建時觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
_注意:`ui` 對象是空對象,包括是為了和其他事件的一致性。_
**Code examples:**
使用指定的 create 回調初始化一個selectable:
```
$( ".selector" ).selectable({
create: function( event, ui ) {}
});
```
綁定一個事件監聽到 selectablecreate 事件:
```
$( ".selector" ).on( "selectablecreate", function( event, ui ) {} );
```
### selected( event, ui )Type: `selectableselected`
此事件會在選擇操作結束時,在添加到選擇的每個元素上觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
* **selected**Type: [Element](http://api.jquery.com/Types/#Element)已被選擇的selectable項。
**Code examples:**
使用指定的 selected 回調初始化一個selectable:
```
$( ".selector" ).selectable({
selected: function( event, ui ) {}
});
```
綁定一個事件監聽到selectableselected事件:
```
$( ".selector" ).on( "selectableselected", function( event, ui ) {} );
```
### selecting( event, ui )Type: `selectableselecting`
此事件會在選擇操作過程中,在添加到選擇的每個元素上觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
* **selecting**Type: [Element](http://api.jquery.com/Types/#Element)當前已被選擇的selectable項。
**Code examples:**
使用指定的 selecting 回調初始化一個selectablec:
```
$( ".selector" ).selectable({
selecting: function( event, ui ) {}
});
```
綁定一個事件監聽到 selectableselecting 事件:
```
$( ".selector" ).on( "selectableselecting", function( event, ui ) {} );
```
### start( event, ui )Type: `selectablestart`
這個事件將在選擇操作開始時觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
_注意:`ui` 對象是空對象,包括是為了和其他事件的一致性。_
**Code examples:**
使用指定的 start 回調初始化一個selectable:
```
$( ".selector" ).selectable({
start: function( event, ui ) {}
});
```
綁定一個事件監聽到 selectablestart 事件:
```
$( ".selector" ).on( "selectablestart", function( event, ui ) {} );
```
### stop( event, ui )Type: `selectablestop`
這個事件將在選擇操作結束后觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
_注意:`ui` 對象是空對象,包括是為了和其他事件的一致性。_
**Code examples:**
使用指定的 stop 回調初始化一個selectable:
```
$( ".selector" ).selectable({
stop: function( event, ui ) {}
});
```
綁定一個事件監聽到 selectablestop 事件:
```
$( ".selector" ).on( "selectablestop", function( event, ui ) {} );
```
### unselected( event, ui )Type: `selectableunselected`
此事件會在選擇操作結束時,在從選擇元素集合中移除的每個元素上觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
* **unselected**Type: [Element](http://api.jquery.com/Types/#Element)已被取消選中的可選擇項。
**Code examples:**
使用指定的 unselected 回調初始化一個selectable:
```
$( ".selector" ).selectable({
unselected: function( event, ui ) {}
});
```
綁定一個事件監聽到 selectableunselected 事件:
```
$( ".selector" ).on( "selectableunselected", function( event, ui ) {} );
```
### unselecting( event, ui )Type: `selectableunselecting`
此事件會在選擇操作過程中,在從選擇元素集合中移除的每個元素上觸發。
* **event**Type: [Event](http://api.jquery.com/Types/#Event)
* **ui**Type: [Object](http://api.jquery.com/Types/#Object)
* **unselecting**Type: [Element](http://api.jquery.com/Types/#Element)當前已被取消選中的可選擇項。
**Code examples:**
使用指定的 unselecting 回調初始化一個selectable:
```
$( ".selector" ).selectable({
unselecting: function( event, ui ) {}
});
```
綁定一個事件監聽到 selectableunselecting 事件:
```
$( ".selector" ).on( "selectableunselecting", function( event, ui ) {} );
```
## Example:
#### A simple jQuery UI Selectable.
```
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>selectable demo</title>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css">
<style>
#selectable .ui-selecting {
background: #ccc;
}
#selectable .ui-selected {
background: #999;
}
</style>
<script src="http://code.jquery.com/jquery-1.9.1.js"></script>
<script src="http://code.jquery.com/ui/1.10.3/jquery-ui.js"></script>
</head>
<body>
<ul id="selectable">
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
<li>Item 4</li>
<li>Item 5</li>
</ul>
<script>
$( "#selectable" ).selectable();
</script>
</body>
</html>
```
- 索引
- Effects
- .addClass()
- Blind Effect
- Bounce Effect
- Clip Effect
- Color Animation
- Drop Effect
- Easings
- .effect()
- Explode Effect
- Fade Effect
- Fold Effect
- .hide()
- Highlight Effect
- Puff Effect
- Pulsate Effect
- .removeClass()
- Scale Effect
- Shake Effect
- .show()
- Size Effect
- Slide Effect
- .switchClass()
- .toggle()
- .toggleClass()
- Transfer Effect
- Effect Core
- .addClass()
- Color Animation
- .effect()
- .hide()
- .removeClass()
- .show()
- .switchClass()
- .toggle()
- .toggleClass()
- Interactions
- Draggable Widget
- Droppable Widget
- Mouse Interaction
- Resizable Widget
- Resizable Widget
- Selectable Widget
- Sortable Widget
- Method Overrides
- .addClass()
- .focus()
- .hide()
- .position()
- .removeClass()
- .show()
- .toggle()
- .toggleClass()
- Methods
- .disableSelection()
- .effect()
- .enableSelection()
- .focus()
- .hide()
- .position()
- .removeUniqueId()
- .scrollParent()
- .show()
- .toggle()
- .uniqueId()
- .zIndex()
- Selectors
- :data() Selector
- :focusable Selector
- :tabbable Selector
- Theming
- CSS 框架(CSS Framework)
- Icons
- Stacking Elements
- UI Core
- :data() Selector
- .disableSelection()
- .enableSelection()
- .focus()
- :focusable Selector
- .removeUniqueId()
- .scrollParent()
- :tabbable Selector
- .uniqueId()
- .zIndex()
- Utilities
- Easings
- Widget Factory
- Widget Plugin Bridge
- Mouse Interaction
- .position()
- Widgets
- Accordion Widget
- Autocomplete Widget
- Button Widget
- Datepicker Widget
- Dialog Widget
- Menu Widget
- Progressbar Widget
- Slider Widget
- Spinner Widget
- Tabs Widget
- Tooltip Widget