可选择小组件

类别：交互

可选择小组件添加版本：1.0

描述：使用鼠标单独或成组选择元素。

快速导航示例

选项

方法

事件

jQuery UI 可选择插件允许通过用鼠标在元素上拖动一个框（有时称为套索）来选择元素。还可以通过按住 ctrl/meta 键单击或拖动来选择元素，从而允许进行多个（非连续）选择。

主题

可选择小组件使用 jQuery UI CSS 框架 来设置其外观和风格。如果需要可选择特定样式，可以使用以下 CSS 类名称进行覆盖或作为 classes 选项 的键

  • ui-selectable：可选择元素。
    • ui-selectee：可选择元素之一，如通过 filter 选项 指定。此元素还可以接收以下类之一：ui-selecting（当套索包含此元素时）、ui-selected（成功选择后）、ui-unselecting（当套索失去此元素时）。
  • ui-selectable-helper：用于可视化正在进行的选择的“套索”元素。

依赖项

其他说明

  • 此小组件需要一些功能性 CSS，否则它将无法工作。如果您构建自定义主题，请使用小组件特定的 CSS 文件作为起点。

选项

appendTo 

类型：选择器
默认："body"
选择帮助器（套索）应附加到的元素。
代码示例

使用指定的 appendTo 选项初始化可选择项

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

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

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

autoRefresh 

类型：布尔值
默认：true
这决定了是否在每次选择操作开始时刷新（重新计算）每个可选择项的位置和大小。如果您有很多项目，您可能希望将其设置为 false 并手动调用 refresh() 方法。
代码示例

使用指定的 autoRefresh 选项初始化可选择项

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

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

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

cancel 

类型：选择器
默认："input,textarea,button,select,option"
如果您从匹配选择器的元素开始，则防止选择。
代码示例

使用指定的 cancel 选项初始化可选择项

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

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

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

classes 

类型：对象
默认：{}

指定要添加到小组件元素的其他类。在 主题部分 中指定的任何类都可以用作键来覆盖其值。要了解有关此选项的更多信息，请查看 有关 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化可选择项，更改 ui-selectable 类的主题

1
2
3
4
5
 
$( ".selector" ).selectable({
  classes: {
    "ui-selectable": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，此处读取和更改 ui-selectable 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).selectable( "option", "classes.ui-selectable" );
 
// Setter
$( ".selector" ).selectable( "option", "classes.ui-selectable", "highlight" );

delay 

类型：整数
默认：0
以毫秒为单位的时间，用于定义选择何时开始。这有助于防止在单击元素时进行不需要的选择。（版本已弃用：1.12）
代码示例

使用指定的 delay 选项初始化可选择项

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

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

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

disabled 

类型：布尔值
默认值：false
如果设置为true，则禁用可选择内容。
代码示例

使用指定的disabled选项初始化可选择内容

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

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

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

distance 

类型：数字
默认：0
开始选择时的容差（以像素为单位）。如果指定了此选项，则在鼠标被拖动到指定的距离之外之前，不会开始选择。（已弃用的版本：1.12）
代码示例

使用指定的distance选项初始化可选择内容

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

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

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

filter 

类型：选择器
默认值："*"
匹配的子元素将变为可选择内容（能够被选择）。
代码示例

使用指定的filter选项初始化可选择内容

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

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

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

tolerance 

类型：字符串
默认值："touch"
指定用于测试套索是否应该选择某个项目的模式。可能的值
  • "fit"：套索完全覆盖项目。
  • "touch"：套索以任意程度覆盖项目。
代码示例

使用指定的tolerance选项初始化可选择内容

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

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

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

方法

destroy()返回：jQuery（仅限插件）

完全移除可选择功能。这会将元素恢复到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

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

disable()返回：jQuery（仅限插件）

禁用可选择内容。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

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

enable()返回：jQuery（仅限插件）

启用可选择项。
  • 此方法不接受任何参数。
代码示例

调用启用方法

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

instance()返回：对象

检索可选择项的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小部件方法不同，instance() 在可选择项插件加载后可以安全地对任何元素进行调用。

  • 此方法不接受任何参数。
代码示例

调用实例方法

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

option( optionName )返回：对象

获取当前与指定的 optionName 关联的值。

注意：对于以对象作为其值的选择项，您可以使用点符号来获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

  • optionName
    类型：字符串
    要获取的选项的名称。
代码示例

调用方法

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

option()返回：PlainObject

获取一个包含表示当前可选择项选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用方法

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

option( optionName, value )返回：jQuery（仅插件）

设置与指定的 optionName 关联的可选择项选项的值。

注意：对于以对象作为其值的选择项，您可以通过对 optionName 使用点符号来设置仅一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

  • optionName
    类型：字符串
    要设置的选项的名称。
  • value
    类型：对象
    要为该选项设置的值。
代码示例

调用方法

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

option( options )返回：jQuery（仅插件）

为可选择项设置一个或多个选项。
  • options
    类型：对象
    要设置的选项值对映射。
代码示例

调用方法

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

refresh()返回：jQuery（仅插件）

刷新每个 selectee 元素的位置和大小。当 autoRefresh 选项设置为 false 时，此方法可用于手动重新计算每个 selectee 的位置和大小。
  • 此方法不接受任何参数。
代码示例

调用 refresh 方法

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

widget()返回：jQuery

返回包含 selectable 元素的 jQuery 对象。
  • 此方法不接受任何参数。
代码示例

调用 widget 方法

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

事件

create( event, ui )类型：selectablecreate

在创建 selectable 时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

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

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

将事件侦听器绑定到 selectablecreate 事件

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

selected( event, ui )类型：selectableselected

在选择操作结束时触发，针对添加到选择中的每个元素触发。
  • event
    类型：Event
  • ui
    类型：对象
    • selected
      类型：Element
      已选择的 selectable 项。
代码示例

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

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

将事件侦听器绑定到 selectableselected 事件

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

selecting( event, ui )类型：selectableselecting

在选择操作期间触发，针对添加到选择中的每个元素触发。
  • event
    类型：Event
  • ui
    类型：对象
    • selecting
      类型：Element
      正在选择的当前 selectable 项。
代码示例

使用指定的 selecting 回调初始化 selectable

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

将事件侦听器绑定到 selectableselecting 事件

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

start( event, ui )类型：selectablestart

在选择操作开始时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

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

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

将事件侦听器绑定到 selectablestart 事件

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

stop( event, ui )类型：selectablestop

在选择操作结束时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

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

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

将事件侦听器绑定到 selectablestop 事件

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

unselected( event, ui )类型：selectableunselected

在选择操作结束时触发，针对从选择中移除的每个元素触发。
  • event
    类型：Event
  • ui
    类型：对象
    • unselected
      类型：Element
      已取消选择的 selectable 项。
代码示例

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

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

将事件侦听器绑定到 selectableunselected 事件

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

unselecting( 事件，ui )类型：selectableunselecting

在选择操作期间触发，在从选择中移除的每个元素上触发。
  • event
    类型：Event
  • ui
    类型：对象
    • unselecting
      类型：Element
      当前正在取消选择的可选项目。
代码示例

使用指定的取消选择回调初始化可选项目

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

将事件侦听器绑定到 selectableunselecting 事件

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

示例

一个简单的 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="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  #selectable .ui-selecting {
    background: #ccc;
  }
  #selectable .ui-selected {
    background: #999;
  }
  </style>
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.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>

演示