# jQuery UI API - 可选择小部件（Selectable Widget）
## 所属类别
[交互（Interactions）](ref-interactions.html)
## 用法
**描述：**使用鼠标选择单个元素或一组元素。
**版本新增：**1.0
**依赖：**
* [UI 核心（UI Core）](ref-ui-core.html)
* [部件库（Widget Factory）](api-jQuery-widget.html)
* [鼠标交互（Mouse Interaction）](api-mouse.html)
**注释：**jQuery UI 可选择（Selectable）插件允许通过鼠标拖拽选择元素（有时被称为一个套索）。可以在按住 ctrl/meta 键的同时单击或拖动来选择多个（不连续的）元素。
**附加说明：**该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。
### 快速导航
| 选项 | 方法 | 事件 |
| --- | --- | --- |
| [appendTo](#option-appendTo)[autoRefresh](#option-autoRefresh)[cancel](#option-cancel)[delay](#option-delay)[disabled](#option-disabled)[distance](#option-distance)[filter](#option-filter)[tolerance](#option-tolerance) | [destroy](#method-destroy)[disable](#method-disable)[enable](#method-enable)[option](#method-option)[refresh](#method-refresh)[widget](#method-widget) | [create](#event-create)[selected](#event-selected)[selecting](#event-selecting)[start](#event-start)[stop](#event-stop)[unselected](#event-unselected)[unselecting](#event-unselecting) |
#### appendTo
**类型**：Selector
**描述**：选择助手（套索）要被添加到哪一个元素。
**代码实例：**
初始化带有指定 `appendTo` 选项的 draggable：
```
$( ".selector" ).selectable({ appendTo: "#someElem" });
```
在初始化后，获取或设置 `appendTo` 选项：
```
// getter
var appendTo = $( ".selector" ).selectable( "option", "appendTo" );
// setter
$( ".selector" ).selectable( "option", "appendTo", "#someElem" );
```
**默认值**："body"
#### autoRefresh
**类型**：Boolean
**描述**：该选项决定是否在每个选择操作的开始时更新（重新计算）每个选择项的位置和尺寸。如果您有多个项目，您可能要设置该选项为 false，并手动调用 `[refresh()](#method-refresh)` 方法。
**代码实例：**
初始化带有指定 `autoRefresh` 选项的 draggable：
```
$( ".selector" ).selectable({ autoRefresh: false });
```
在初始化后，获取或设置 `autoRefresh` 选项：
```
// getter
var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );
// setter
$( ".selector" ).selectable( "option", "autoRefresh", false );
```
**默认值**：true
#### cancel
**类型**：Selector
**描述**：防止从匹配选择器的元素上开始选择。
**代码实例：**
初始化带有指定 `cancel` 选项的 selectable：
```
$( ".selector" ).selectable({ cancel: "a,.cancel" });
```
在初始化后，获取或设置 `cancel` 选项：
```
// getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );
// setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );
```
**默认值**："input, textarea, button, select, option"
#### delay
**类型**：Number
**描述**：鼠标按下后直到选择开始的时间，以毫秒计。该选项可以防止点击在某个元素上时不必要的选择。
**代码实例：**
初始化带有指定 `delay` 选项的 selectable：
```
$( ".selector" ).selectable({ delay: 150 });
```
在初始化后，获取或设置 `delay` 选项：
```
// getter
var delay = $( ".selector" ).selectable( "option", "delay" );
// setter
$( ".selector" ).selectable( "option", "delay", 150 );
```
**默认值**：0
#### disabled
**类型**：Boolean
**描述**：如果设置为 `true`，则禁用该 selectable。
**代码实例：**
初始化带有指定 `disabled` 选项的 selectable：
```
$( ".selector" ).selectable({ disabled: true });
```
在初始化后，获取或设置 `disabled` 选项：
```
// getter
var disabled = $( ".selector" ).selectable( "option", "disabled" );
// setter
$( ".selector" ).selectable( "option", "disabled", true );
```
**默认值**：false
#### distance
**类型**：Number
**描述**：鼠标按下后选择开始前必须移动的距离，以像素计。如果指定了该选项，选择只有在鼠标拖拽超出指定距离时才会开始。该选项可以防止点击在某个元素上时不必要的选择。
**代码实例：**
初始化带有指定 `distance` 选项的 selectable：
```
$( ".selector" ).selectable({ distance: 30 });
```
在初始化后，获取或设置 `distance` 选项：
```
// getter
var distance = $( ".selector" ).selectable( "option", "distance" );
// setter
$( ".selector" ).selectable( "option", "distance", 30 );
```
**默认值**：0
#### filter
**类型**：Selector
**描述**：要制作选择项（可被选择的）的匹配的子元素。
**代码实例：**
初始化带有指定 `filter` 选项的 selectable：
```
$( ".selector" ).selectable({ filter: "li" });
```
在初始化后，获取或设置 `filter` 选项：
```
// getter
var filter = $( ".selector" ).selectable( "option", "filter" );
// setter
$( ".selector" ).selectable( "option", "filter", "li" );
```
**默认值**："*"
#### tolerance
**类型**：String
**描述**：指定用于测试套索是否选择一个项目的模式。可能的值：
* `"fit"`：套索完全重叠在项目上。
* `"touch"`：套索重叠在项目上，任何比例皆可。
**代码实例：**
初始化带有指定 `tolerance` 选项的 selectable：
```
$( ".selector" ).selectable({ tolerance: "fit" });
```
在初始化后，获取或设置 `tolerance` 选项：
```
// getter
var tolerance = $( ".selector" ).selectable( "option", "tolerance" );
// setter
$( ".selector" ).selectable( "option", "tolerance", "fit" );
```
**默认值**："touch"
#### 方法
#### destroy()
**类型**：jQuery (plugin only)
**描述**：完全移除 selectable 功能。这会把元素返回到它的预初始化状态。
* 该方法不接受任何参数。
**代码实例：**
调用 destroy 方法：
```
$( ".selector" ).selectable( "destroy" );
```
#### disable()
**类型**：jQuery (plugin only)
**描述**：禁用 selectable。
* 该方法不接受任何参数。
**代码实例：**
调用 disable 方法：
```
$( ".selector" ).selectable( "disable" );
```
#### enable()
**类型**：jQuery (plugin only)
**描述**：启用 selectable。
* 该方法不接受任何参数。
**代码实例：**
调用 enable 方法：
```
$( ".selector" ).selectable( "enable" );
```
#### option( optionName )
**类型**：Object
**描述**：获取当前与指定的 `optionName` 关联的值。
* **optionName**
类型：String
描述：要获取的选项的名称。
**代码实例：**
调用该方法：
```
var isDisabled = $( ".selector" ).selectable( "option", "disabled" );
```
#### option()
**类型**：PlainObject
**描述**：获取一个包含键/值对的对象，键/值对表示当前 selectable 选项哈希。
* 该方法不接受任何参数。
**代码实例：**
调用该方法：
```
var options = $( ".selector" ).selectable( "option" );
```
#### option( optionName, value )
**类型**：jQuery (plugin only)
**描述**：设置与指定的 `optionName` 关联的 selectable 选项的值。
* **optionName**
类型：String
描述：要设置的选项的名称。
* **value**
类型：Object
描述：要为选项设置的值。
**代码实例：**
调用该方法：
```
$( ".selector" ).selectable( "option", "disabled", true );
```
#### option( options )
**类型**：jQuery (plugin only)
**描述**：为 selectable 设置一个或多个选项。
* **options**
类型：Object
描述：要设置的 option-value 对。
**代码实例：**
调用该方法：
```
$( ".selector" ).selectable( "option", { disabled: true } );
```
#### refresh()
**类型**：jQuery (plugin only)
**描述**：更新每个选择项元素的位置和尺寸。当 `[autoRefresh](#option-autoRefresh)` 选项被设置为 false 时，该方法可用于手动重新计算每个选择项的位置和尺寸。
* 该方法不接受任何参数。
**代码实例：**
调用 refresh 方法：
```
$( ".selector" ).selectable( "refresh" );
```
#### widget()
**类型**：jQuery
**描述**：返回一个包含 selectable 元素的 `jQuery` 对象。
* 该方法不接受任何参数。
**代码实例：**
调用 widget 方法：
```
var widget = $( ".selector" ).selectable( "widget" );
```
#### 事件
#### create( event, ui )
**类型**：selectablecreate
**描述**：当 selectable 被创建时触发。
* **event**
类型：Event
* **ui**
类型：Object
注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。
**代码实例：**
初始化带有指定 create 回调的 selectable：
```
$( ".selector" ).selectable({
create: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectablecreate 事件：
```
$( ".selector" ).on( "selectablecreate", function( event, ui ) {} );
```
#### selected( event, ui )
**类型**：selectableselected
**描述**：当每个元素被添加选择时，在选择操作结尾触发。
* **event**
类型：Event
* **ui**
类型：Object
* **selected**
类型：Element
描述：被选择的可选择项目。
**代码实例：**
初始化带有指定 selected 回调的 selectable：
```
$( ".selector" ).selectable({
selected: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectableselected 事件：
```
$( ".selector" ).on( "selectableselected", function( event, ui ) {} );
```
#### selecting( event, ui )
**类型**：selectableselecting
**描述**：当每个元素被添加选择时，在选择操作期间触发。
* **event**
类型：Event
* **ui**
类型：Object
* **selecting**
类型：Element
描述：正被选择的当前可选择项目。
**代码实例：**
初始化带有指定 selecting 回调的 selectable：
```
$( ".selector" ).selectable({
selecting: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectableselecting 事件：
```
$( ".selector" ).on( "selectableselecting", function( event, ui ) {} );
```
#### start( event, ui )
**类型**：selectablestart
**描述**：在选择操作开头触发。
* **event**
类型：Event
* **ui**
类型：Object
注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。
**代码实例：**
初始化带有指定 start 回调的 selectable：
```
$( ".selector" ).selectable({
start: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectablestart 事件：
```
$( ".selector" ).on( "selectablestart", function( event, ui ) {} );
```
#### stop( event, ui )
**类型**：selectablestop
**描述**：在选择操作结尾触发。
* **event**
类型：Event
* **ui**
类型：Object
注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。
**代码实例：**
初始化带有指定 stop 回调的 selectable：
```
$( ".selector" ).selectable({
stop: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectablestop 事件：
```
$( ".selector" ).on( "selectablestop", function( event, ui ) {} );
```
#### unselected( event, ui )
**类型**：selectableunselected
**描述**：当每个元素从选择中被移除时，在选择操作结尾触发。
* **event**
类型：Event
* **ui**
类型：Object
* **unselected**
类型：Element
描述：未被选择的可选择项目。
**代码实例：**
初始化带有指定 unselected 回调的 selectable：
```
$( ".selector" ).selectable({
unselected: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectableunselected 事件：
```
$( ".selector" ).on( "selectableunselected", function( event, ui ) {} );
```
#### unselecting( event, ui )
**类型**：selectableunselecting
**描述**：当每个元素从选择中被移除时，在选择操作期间触发。
* **event**
类型：Event
* **ui**
类型：Object
* **unselecting**
类型：Element
描述：正未被选择的当前可选择项目。
**代码实例：**
初始化带有指定 unselecting 回调的 selectable：
```
$( ".selector" ).selectable({
unselecting: function( event, ui ) {}
});
```
绑定一个事件监听器到 selectableunselecting 事件：
```
$( ".selector" ).on( "selectableunselecting", function( event, ui ) {} );
```
## 实例
一个简单的 jQuery UI 可选择小部件（Selectable Widget）。
```
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>可选择小部件（Selectable Widget）演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<style>
#selectable .ui-selecting {
background: #ccc;
}
#selectable .ui-selected {
background: #999;
}
</style>
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/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>
```
- jQuery UI 基础
- jQuery UI 简介
- jQuery UI 下载
- jQuery UI 使用
- jQuery UI 定制
- jQuery UI 工作原理
- jQuery UI 主题
- jQuery UI 主题
- jQuery UI ThemeRoller
- jQuery UI CSS 框架 API
- jQuery UI 设计主题
- jQuery UI 部件库
- jQuery UI 部件库（Widget Factory）
- jQuery UI 通过部件库（Widget Factory）扩展小部件
- jQuery UI 小部件（Widget）方法调用
- jQuery UI 为什么使用部件库（Widget Factory）
- jQuery UI 如何使用部件库（Widget Factory）
- jQuery UI 实例
- jQuery UI 实例
- jQuery UI 实例 - 拖动（Draggable）
- jQuery UI 实例 - 放置（Droppable）
- jQuery UI 实例 - 缩放（Resizable）
- jQuery UI 实例 - 选择（Selectable）
- jQuery UI 实例 - 排序（Sortable）
- jQuery UI 实例 - 折叠面板（Accordion）
- jQuery UI 实例 - 自动完成（Autocomplete）
- jQuery UI 实例 - 按钮（Button）
- jQuery UI 实例 - 日期选择器（Datepicker）
- jQuery UI 实例 - 对话框（Dialog）
- jQuery UI 实例 - 菜单（Menu）
- jQuery UI 实例 - 进度条（Progressbar）
- jQuery UI 实例 - 滑块（Slider）
- jQuery UI 实例 - 旋转器（Spinner）
- jQuery UI 实例 - 标签页（Tabs）
- jQuery UI 实例 - 工具提示框（Tooltip）
- jQuery UI 实例 - 特效（Effect）
- jQuery UI 实例 - 显示（Show）
- jQuery UI 实例 - 隐藏（Hide）
- jQuery UI 实例 - 切换（Toggle）
- jQuery UI 实例 - 添加 Class（Add Class）
- jQuery UI 实例 - 移除 Class（Remove Class）
- jQuery UI 实例 - 切换 Class（Toggle Class）
- jQuery UI 实例 - 转换 Class（Switch Class）
- jQuery UI 实例 - 颜色动画（Color Animation）
- jQuery UI 实例 - 定位（Position）
- jQuery UI 实例 - 部件库（Widget Factory）
- jQuery UI API 参考
- jQuery UI API 类别 - 特效（Effects）
- jQuery UI API - .addClass()
- jQuery UI API - 百叶窗特效（Blind Effect）
- jQuery UI API - 反弹特效（Bounce Effect）
- jQuery UI API - 剪辑特效（Clip Effect）
- jQuery UI API - 颜色动画（Color Animation）
- jQuery UI API - 降落特效（Drop Effect）
- jQuery UI API - Easings
- jQuery UI API - .effect()
- jQuery UI API - 爆炸特效（Explode Effect）
- jQuery UI API - 淡入淡出特效（Fade Effect）
- jQuery UI API - 折叠特效（Fold Effect）
- jQuery UI API - .hide()
- jQuery UI API - 突出特效（Highlight Effect）
- jQuery UI API - 膨胀特效（Puff Effect）
- jQuery UI API - 跳动特效（Pulsate Effect）
- jQuery UI API - .removeClass()
- jQuery UI API - 缩放特效（Scale Effect）
- jQuery UI API - 震动特效（Shake Effect）
- jQuery UI API - .show()
- jQuery UI API - 尺寸特效（Size Effect）
- jQuery UI API - 滑动特效（Slide Effect）
- jQuery UI API - .switchClass()
- jQuery UI API - .toggle()
- jQuery UI API - .toggleClass()
- jQuery UI API - 转移特效（Transfer Effect）
- jQuery UI API 类别 - 特效核心（Effects Core）
- jQuery UI API - 颜色动画（Color Animation）
- jQuery UI API 类别 - 交互（Interactions）
- jQuery UI API - 可拖拽小部件（Draggable Widget）
- jQuery UI API - 可放置小部件（Droppable Widget）
- jQuery UI API - 鼠标交互（Mouse Interaction）
- jQuery UI API - 可调整尺寸小部件（Resizable Widget）
- jQuery UI API - 可选择小部件（Selectable Widget）
- jQuery UI API - 可排序小部件（Sortable Widget）
- jQuery UI API 类别 - 方法重载（Method Overrides）
- jQuery UI API - .focus()
- jQuery UI API - .position()
- jQuery UI API 类别 - 方法（Methods）
- jQuery UI API - .disableSelection()
- jQuery UI API - .enableSelection()
- jQuery UI API - .removeUniqueId()
- jQuery UI API - .scrollParent()
- jQuery UI API - .uniqueId()
- jQuery UI API - .zIndex()
- jQuery UI API 类别 - 选择器（Selectors）
- jQuery UI API - :data() Selector
- jQuery UI API - :focusable Selector
- jQuery UI API - :tabbable Selector
- jQuery UI API 类别 - 主题（Theming）
- jQuery UI API - CSS 框架（CSS Framework）
- jQuery UI API - 图标（Icons）
- jQuery UI API - 堆叠元素（Stacking Elements）
- jQuery UI API 类别 - UI 核心（UI Core）
- jQuery UI API 类别 - 实用工具（Utilities）
- jQuery UI API - 部件库（Widget Factory）
- jQuery UI API - 插件桥（Widget Plugin Bridge）
- jQuery UI API 类别 - 小部件（Widgets）
- jQuery UI API - 折叠面板部件（Accordion Widget）
- jQuery UI API - 自动完成部件（Autocomplete Widget）
- jQuery UI API - 按钮部件（Button Widget）
- jQuery UI API - 日期选择器部件（Datepicker Widget）
- jQuery UI API - 对话框部件（Dialog Widget）
- jQuery UI API - 菜单部件（Menu Widget）
- jQuery UI API - 进度条部件（Progressbar Widget）
- jQuery UI API - 滑块部件（Slider Widget）
- jQuery UI API - 旋转器部件（Spinner Widget）
- jQuery UI API - 标签页部件（Tabs Widget）
- jQuery UI API - 工具提示框部件（Tooltip Widget）
- jQuery EasyUI 简介
- jQuery EasyUI 应用
- jQuery EasyUI 应用 - 创建 CRUD 应用
- jQuery EasyUI 应用 - 创建 CRUD 数据网格（DataGrid）
- jQuery EasyUI 应用 - 创建展开行明细编辑表单的 CRUD 应用
- jQuery EasyUI 应用 - 创建 RSS Feed 阅读器
- jQuery EasyUI 拖放
- jQuery EasyUI 拖放 - 基本的拖动和放置
- jQuery EasyUI 拖放 - 创建拖放的购物车
- jQuery EasyUI 拖放 - 创建学校课程表
- jQuery EasyUI 菜单与按钮
- jQuery EasyUI 菜单与按钮 - 创建简单的菜单
- jQuery EasyUI 菜单与按钮 - 创建链接按钮（Link Button）
- jQuery EasyUI 菜单与按钮 - 创建菜单按钮（Menu Button）
- jQuery EasyUI 菜单与按钮 - 创建分割按钮（Split Button）
- jQuery EasyUI 布局
- jQuery EasyUI 布局 - 为网页创建边框布局
- jQuery EasyUI 布局 - 在面板中创建复杂布局
- jQuery EasyUI 布局 - 创建折叠面板
- jQuery EasyUI 布局 - 创建标签页（Tabs）
- jQuery EasyUI 布局 - 动态添加标签页（Tabs）
- jQuery EasyUI 布局 - 添加自动播放标签页（Tabs）
- jQuery EasyUI 布局 - 创建 XP 风格左侧面板
- jQuery EasyUI 数据网格
- jQuery EasyUI 数据网格 - 转换 HTML 表格为数据网格
- jQuery EasyUI 数据网格 - 取得选中行数据
- jQuery EasyUI 数据网格 - 添加查询功能
- jQuery EasyUI 数据网格 - 添加工具栏
- jQuery EasyUI 数据网格 - 创建复杂工具栏
- jQuery EasyUI 数据网格 - 设置冻结列
- jQuery EasyUI 数据网格 - 动态改变列
- jQuery EasyUI 数据网格 - 格式化列
- jQuery EasyUI 数据网格 - 设置排序
- jQuery EasyUI 数据网格 - 自定义排序
- jQuery EasyUI 数据网格 - 创建列组合
- jQuery EasyUI 数据网格 - 添加复选框
- jQuery EasyUI 数据网格 - 自定义分页
- jQuery EasyUI 数据网格 - 启用行内编辑
- jQuery EasyUI 数据网格 - 扩展编辑器
- jQuery EasyUI 数据网格 - 列运算
- jQuery EasyUI 数据网格 - 合并单元格
- jQuery EasyUI 数据网格 - 创建自定义视图
- jQuery EasyUI 数据网格 - 创建页脚摘要
- jQuery EasyUI 数据网格 - 条件设置行背景颜色
- jQuery EasyUI 数据网格 - 创建属性网格
- jQuery EasyUI 数据网格 - 扩展行显示细节
- jQuery EasyUI 数据网格 - 创建子网格
- jQuery EasyUI 数据网格 - 使用虚拟滚动视图显示海量数据
- jQuery EasyUI 数据网格 - 添加分页组件
- jQuery EasyUI 窗口
- jQuery EasyUI 窗口 - 创建简单窗口
- jQuery EasyUI 窗口 - 自定义窗口工具栏
- jQuery EasyUI 窗口 - 窗口与布局
- jQuery EasyUI 窗口 - 创建对话框
- jQuery EasyUI 窗口 - 自定义带有工具条和按钮的对话框
- jQuery EasyUI 树形菜单
- jQuery EasyUI 树形菜单 - 使用标记创建树形菜单
- jQuery EasyUI 树形菜单 - 创建异步树形菜单
- jQuery EasyUI 树形菜单 - 树形菜单添加节点
- jQuery EasyUI 树形菜单 - 创建带复选框的树形菜单
- jQuery EasyUI 树形菜单 - 树形菜单拖放控制
- jQuery EasyUI 树形菜单 - 树形菜单加载父/子节点
- jQuery EasyUI 树形菜单 - 创建基础树形网格
- jQuery EasyUI 树形菜单 - 创建复杂树形网格
- jQuery EasyUI 树形菜单 - 树形网格动态加载
- jQuery EasyUI 树形菜单 - 树形网格添加分页
- jQuery EasyUI 树形菜单 - 树形网格惰性加载节点
- jQuery EasyUI 表单
- jQuery EasyUI 表单 - 创建异步提交表单
- jQuery EasyUI 表单 - 表单验证
- jQuery EasyUI 表单 - 创建树形下拉框
- jQuery EasyUI 表单 - 格式化下拉框
- jQuery EasyUI 表单 - 过滤下拉数据网格
- jQuery EasyUI 插件
- jQuery EasyUI 扩展
- 免责声明