所属类别
交互(Interactions)
用法
描述:使用鼠标选择单个元素或一组元素。
版本新增:1.0
依赖:
注释:jQuery UI 可选择(Selectable)插件允许通过鼠标拖拽选择元素(有时被称为一个套索)。可以在按住 ctrl/meta 键的同时单击或拖动来选择多个(不连续的)元素。
附加说明:该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。
快速导航
选项 |
类型 |
描述 |
默认值 |
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() 方法。
代码实例:
初始化带有指定 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 选项被设置为 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>