# 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