Selectable Widget

Categories: Interactions

version added: 1.0

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

QuickNavExamples

Options

• appendTo
• autoRefresh
• cancel
• delay
• disabled
• distance
• filter
• tolerance

Methods

• destroy
• disable
• enable
• option
• refresh
• widget

Events

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

依赖关系

• UI Core
• Widget Factory
• Mouse Interaction

其他注意事项：

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

Options

appendToType: 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" );

autoRefreshType: Boolean

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

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

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

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

// 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 :

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

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

// getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );

// setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );

delayType: 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 );

disabledType: 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 );

distanceType: 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 );

filterType: Selector

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

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

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

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

// getter
var filter = $( ".selector" ).selectable( "option", "filter" );

// setter
$( ".selector" ).selectable( "option", "filter", "li" );

toleranceType: 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

通过指定的optionName，获取当前关联的值。

• optionNameType: String要获取值的选项名

Code examples:

调用 方法:

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

option()Returns: PlainObject

获取一个对象，它包含表示当前resizable的选项hash的键/值对。

• 这个方法不接受任何参数。

Code examples:

调用这个方法:

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

option( optionName, value )

通过指定的optionName，设置selectable的相关选项值。

• optionNameType: String要设置值的选项名。
• valueType: Object要设置选项的值。

Code examples:

调用这个方法:

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

option( options )

为selectable设置一个或多个选项。

• optionsType: Object用来设置的选项/值对的对象。

Code examples:

调用这个方法:

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

refresh()

刷新每个选择项的位置和大小. 这个方法用来手动重新计算选择项的位置和大小,在autoRefresh设置为false时很有用。

• 这个方法不接受任何参数。

Code examples:

调用 refresh 方法:

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

widget()Returns: jQuery

返回一个jQuery，它包含了selectable元素。

• 这个方法不接受任何参数。

Code examples:

调用 widget 方法:

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

Events

create( event, ui )Type: selectablecreate

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

• eventType: Event
• uiType: Object

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

Code examples:

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

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

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

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

selected( event, ui )Type: selectableselected

此事件会在选择操作结束时，在添加到选择的每个元素上触发。

• eventType: Event
• uiType: Object
  • selectedType: Element已被选择的selectable项。

Code examples:

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

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

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

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

selecting( event, ui )Type: selectableselecting

此事件会在选择操作过程中，在添加到选择的每个元素上触发。

• eventType: Event
• uiType: Object
  • selectingType: Element当前已被选择的selectable项。

Code examples:

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

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

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

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

start( event, ui )Type: selectablestart

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

• eventType: Event
• uiType: Object

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

Code examples:

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

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

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

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

stop( event, ui )Type: selectablestop

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

• eventType: Event
• uiType: Object

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

Code examples:

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

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

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

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

unselected( event, ui )Type: selectableunselected

此事件会在选择操作结束时，在从选择元素集合中移除的每个元素上触发。

• eventType: Event
• uiType: Object
  • unselectedType: Element已被取消选中的可选择项。

Code examples:

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

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

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

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

unselecting( event, ui )Type: selectableunselecting

此事件会在选择操作过程中，在从选择元素集合中移除的每个元素上触发。

• eventType: Event
• uiType: Object
  • unselectingType: 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>