jQuery UI API - 可选择小部件（Selectable Widget）

所属类别

交互（Interactions）

用法

描述：使用鼠标选择单个元素或一组元素。

版本新增：1.0

依赖：

注释：jQuery UI 可选择（Selectable）插件允许通过鼠标拖拽选择元素（有时被称为一个套索）。可以在按住 ctrl/meta 键的同时单击或拖动来选择多个（不连续的）元素。

附加说明：该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。

快速导航

选项 方法 事件
appendToautoRefreshcanceldelaydisableddistancefiltertolerance destroydisableenableoptionrefreshwidget createselectedselectingstartstopunselectedunselecting

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>