Selectable Widget

Categories: Interactions

Selectable Widgetversion added: 1.0

Description: 使用鼠标选择一个或一组元素。

QuickNavExamples

Options

Methods

Events

jQuery UI Selectable 插件允许一个元素被鼠标划出的选择区域选中. 同样, 元素也可以被点击选中或者同时按住 Ctrl/Meta键, 允许多个(非连续)的选择.

依赖关系

其他注意事项：

  • 这个widget需要一些功能性的CSS，否则将无法正常工作。 如果你建立一个自定义的主题，使用widget指定的CSS文件作为一个激活点。

Options

appendToType: Selector

Default: "body"
选择帮手（套索） 应追加到哪个元素 。
Code examples:

使用指定的 appendTo 参数初始化selectable :

1
 
$( ".selector" ).selectable({ appendTo: "#someElem" });

在初始化后设置或者获取 appendTo 选项 :

1
2
3
4
5
6
 
// getter
var appendTo = $( ".selector" ).selectable( "option", "appendTo" );
 
 
// setter
$( ".selector" ).selectable( "option", "appendTo", "#someElem" );

autoRefreshType: Boolean

Default: true
这个选项确定每个选择操作开始时如何刷新(重新计算)每个选择项的位置和大小. 如果你有很多很多选择项, 你应当设置此项为false并且手动调用refresh() 方法.
Code examples:

使用指定的 autoRefresh 参数初始化selectable :

1
 
$( ".selector" ).selectable({ autoRefresh: false });

在初始化后设置或者获取 autoRefresh 选项 :

1
2
3
4
5
6
 
// getter
var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );
 
 
// setter
$( ".selector" ).selectable( "option", "autoRefresh", false );

cancelType: Selector

Default: "input,textarea,button,select,option"
如果你使用了匹配选择器,符合匹配的元素将被禁止可选.
Code examples:

使用指定的 cancel 参数初始化selectable :

1
 
$( ".selector" ).selectable({ cancel: "a,.cancel" });

在初始化后设置或者获取 cancel 选项 :

1
2
3
4
5
6
 
// getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );
 
 
// setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );

delayType: Integer

Default: 0
定义需要经过多少毫秒后选择才会开始. 这可以预防意外的点击造成元素被选择.
Code examples:

使用指定的 delay 参数初始化selectable :

1
 
$( ".selector" ).selectable({ delay: 150 });

在初始化后设置或者获取 delay 选项 :

1
2
3
4
5
6
 
// getter
var delay = $( ".selector" ).selectable( "option", "delay" );
 
 
// setter
$( ".selector" ).selectable( "option", "delay", 150 );

disabledType: Boolean

Default: false
如果设置为 true 将禁止selectable。
Code examples:

使用指定的 disabled 参数初始化selectable :

1
 
$( ".selector" ).selectable({ disabled: true });

在初始化后设置或者获取 disabled 选项 :

1
2
3
4
5
6
 
// getter
var disabled = $( ".selector" ).selectable( "option", "disabled" );
 
 
// setter
$( ".selector" ).selectable( "option", "disabled", true );

distanceType: Number

Default: 0
定义需要移动多少个像素选择才会开始. 如果指定了该项, 选择不会马上开始,而是会在鼠标移动了指定像素的距离之后才会开始.
Code examples:

使用指定的 distance 参数初始化selectable :

1
 
$( ".selector" ).selectable({ distance: 30 });

在初始化后设置或者获取 distance 选项 :

1
2
3
4
5
6
 
// getter
var distance = $( ".selector" ).selectable( "option", "distance" );
 
 
// setter
$( ".selector" ).selectable( "option", "distance", 30 );

filterType: Selector

Default: "*"
匹配子元素中那些符合条件的元素才可以被选择.
Code examples:

使用指定的 filter 参数初始化selectable :

1
 
$( ".selector" ).selectable({ filter: "li" });

在初始化后设置或者获取 filter 选项 :

1
2
3
4
5
6
 
// getter
var filter = $( ".selector" ).selectable( "option", "filter" );
 
 
// setter
$( ".selector" ).selectable( "option", "filter", "li" );

toleranceType: String

Default: "touch"
指定那种模式，用来测试套索是否应该选择一个项目。允许使用的值:
  • "fit": 套索完全重叠的项目。
  • "touch": 套索重叠的项目任何部分。
Code examples:

使用指定的 tolerance 参数初始化selectable :

1
 
$( ".selector" ).selectable({ tolerance: "fit" });

在初始化后设置或者获取 tolerance 选项 :

1
2
3
4
5
6
 
// getter
var tolerance = $( ".selector" ).selectable( "option", "tolerance" );
 
 
// setter
$( ".selector" ).selectable( "option", "tolerance", "fit" );

Methods

destroy()

完全移除selectable功能. 这将使元素返回到之前的初始化状态.
  • 这个方法不接受任何参数。
Code examples:

调用 destroy 方法:

1
 
$( ".selector" ).selectable( "destroy" );

disable()

禁用selectable.
  • 这个方法不接受任何参数。
Code examples:

调用 disable 方法:

1
 
$( ".selector" ).selectable( "disable" );

enable()

启用 selectable.
  • 这个方法不接受任何参数。
Code examples:

调用 enable 方法:

1
 
$( ".selector" ).selectable( "enable" );

option( optionName )Returns: Object

通过指定的optionName，获取当前关联的值。
  • optionName
    Type: String
    要获取值的选项名
Code examples:

调用 方法:

1
 
var isDisabled = $( ".selector" ).selectable( "option", "disabled" );

option()Returns: PlainObject

获取一个对象，它包含表示当前resizable的选项hash的键/值对。
  • 这个方法不接受任何参数。
Code examples:

调用这个方法:

1
 
var options = $( ".selector" ).selectable( "option" );

option( optionName, value )

通过指定的optionName，设置selectable的相关选项值。
  • optionName
    Type: String
    要设置值的选项名。
  • value
    Type: Object
    要设置选项的值。
Code examples:

调用这个方法:

1
 
$( ".selector" ).selectable( "option", "disabled", true );

option( options )

为selectable设置一个或多个选项。
  • options
    Type: Object
    用来设置的选项/值对的对象。
Code examples:

调用这个方法:

1
 
$( ".selector" ).selectable( "option", { disabled: true } );

refresh()

刷新每个选择项的位置和大小. 这个方法用来手动重新计算选择项的位置和大小,在autoRefresh设置为false时很有用。
  • 这个方法不接受任何参数。
Code examples:

调用 refresh 方法:

1
 
$( ".selector" ).selectable( "refresh" );

widget()Returns: jQuery

返回一个jQuery，它包含了selectable元素。
  • 这个方法不接受任何参数。
Code examples:

调用 widget 方法:

1
 
var widget = $( ".selector" ).selectable( "widget" );

Events

create( event, ui )Type: selectablecreate

此事件会在 selectable 创建时触发。

注意：ui 对象是空对象，包括是为了和其他事件的一致性。

Code examples:

使用指定的 create 回调初始化一个selectable：

1
2
3
 
$( ".selector" ).selectable({
  create: function( event, ui ) {}
});

绑定一个事件监听到 selectablecreate 事件：

1
 
$( ".selector" ).on( "selectablecreate", function( event, ui ) {} );

selected( event, ui )Type: selectableselected

此事件会在选择操作结束时，在添加到选择的每个元素上触发。
  • event
    Type: Event
  • ui
    Type: Object
    • selected
      Type: Element
      已被选择的selectable项。
Code examples:

使用指定的 selected 回调初始化一个selectable：

1
2
3
 
$( ".selector" ).selectable({
  selected: function( event, ui ) {}
});

绑定一个事件监听到selectableselected事件：

1
 
$( ".selector" ).on( "selectableselected", function( event, ui ) {} );

selecting( event, ui )Type: selectableselecting

此事件会在选择操作过程中，在添加到选择的每个元素上触发。
  • event
    Type: Event
  • ui
    Type: Object
    • selecting
      Type: Element
      当前已被选择的selectable项。
Code examples:

使用指定的 selecting 回调初始化一个selectablec：

1
2
3
 
$( ".selector" ).selectable({
  selecting: function( event, ui ) {}
});

绑定一个事件监听到 selectableselecting 事件：

1
 
$( ".selector" ).on( "selectableselecting", function( event, ui ) {} );

start( event, ui )Type: selectablestart

这个事件将在选择操作开始时触发。

注意：ui 对象是空对象，包括是为了和其他事件的一致性。

Code examples:

使用指定的 start 回调初始化一个selectable：

1
2
3
 
$( ".selector" ).selectable({
  start: function( event, ui ) {}
});

绑定一个事件监听到 selectablestart 事件：

1
 
$( ".selector" ).on( "selectablestart", function( event, ui ) {} );

stop( event, ui )Type: selectablestop

这个事件将在选择操作结束后触发。

注意：ui 对象是空对象，包括是为了和其他事件的一致性。

Code examples:

使用指定的 stop 回调初始化一个selectable：

1
2
3
 
$( ".selector" ).selectable({
  stop: function( event, ui ) {}
});

绑定一个事件监听到 selectablestop 事件：

1
 
$( ".selector" ).on( "selectablestop", function( event, ui ) {} );

unselected( event, ui )Type: selectableunselected

此事件会在选择操作结束时，在从选择元素集合中移除的每个元素上触发。
  • event
    Type: Event
  • ui
    Type: Object
    • unselected
      Type: Element
      已被取消选中的可选择项。
Code examples:

使用指定的 unselected 回调初始化一个selectable：

1
2
3
 
$( ".selector" ).selectable({
  unselected: function( event, ui ) {}
});

绑定一个事件监听到 selectableunselected 事件：

1
 
$( ".selector" ).on( "selectableunselected", function( event, ui ) {} );

unselecting( event, ui )Type: selectableunselecting

此事件会在选择操作过程中，在从选择元素集合中移除的每个元素上触发。
  • event
    Type: Event
  • ui
    Type: Object
    • unselecting
      Type: Element
      当前已被取消选中的可选择项。
Code examples:

使用指定的 unselecting 回调初始化一个selectable：

1
2
3
 
$( ".selector" ).selectable({
  unselecting: function( event, ui ) {}
});

绑定一个事件监听到 selectableunselecting 事件：

1
 
$( ".selector" ).on( "selectableunselecting", function( event, ui ) {} );

Example:

A simple jQuery UI Selectable.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
<!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>

Demo: