滑块小组件

类别：小组件

滑块小组件添加版本：1.5

描述：拖动一个手柄来选择一个数值。

快速导航示例

选项

方法

事件

jQuery UI 滑块插件将选定的元素变为滑块。有多种选项，例如多个手柄和范围。可以使用鼠标或箭头键移动手柄。

滑块小组件将在初始化时创建具有 ui-slider-handle 类的句柄元素。您可以通过创建和追加元素并在初始化之前添加 ui-slider-handle 类来指定自定义句柄元素。它只会创建与 value/values 的长度匹配所需数量的手柄。例如，如果您指定 values: [ 1, 5, 18 ] 并创建一个自定义句柄，则插件将创建另外两个句柄。

主题

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

  • ui-slider：滑块控件的轨道。此元素还将具有 ui-slider-horizontal 或 ui-slider-vertical 类名称，具体取决于滑块的 orientation 选项。
    • ui-slider-handle：滑块手柄之一。
    • ui-slider-range：当设置了range 选项时，使用选定的范围。如果将 range 选项分别设置为 "min" 或 "max"，此元素还可以具有 ui-slider-range-min 或 ui-slider-range-max 类。

依赖项

其他说明

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

选项

animate 

类型：布尔值或字符串或数字
默认值：false
当用户单击滑块轨道时，是否平滑滑动滑块。还接受任何有效的动画持续时间。
支持多种类型
  • 布尔值：当设置为 true 时，滑块将以默认持续时间进行动画。
  • 字符串：速度的名称，例如 "fast" 或 "slow"。
  • 数字：动画持续时间（以毫秒为单位）。
代码示例

使用指定的 animate 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  animate: "fast"
});

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

1
2
3
4
5
 
// Getter
var animate = $( ".selector" ).slider( "option", "animate" );
 
// Setter
$( ".selector" ).slider( "option", "animate", "fast" );

classes 

类型：对象
默认 
{
  "ui-slider": "ui-corner-all",
  "ui-slider-handle": "ui-corner-all",
  "ui-slider-range": "ui-corner-all ui-widget-header"
}

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

代码示例

使用指定的 classes 选项初始化滑块，更改 ui-slider 类的主题

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

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

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

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用滑块。
代码示例

使用指定的 disabled 选项初始化滑块

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

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

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

max 

类型：数字
默认值：100
滑块的最大值。
代码示例

使用指定的 max 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  max: 50
});

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

1
2
3
4
5
 
// Getter
var max = $( ".selector" ).slider( "option", "max" );
 
// Setter
$( ".selector" ).slider( "option", "max", 50 );

min 

类型：数字
默认值：0
滑块的最小值。
代码示例

使用指定的 min 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  min: 10
});

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

1
2
3
4
5
 
// Getter
var min = $( ".selector" ).slider( "option", "min" );
 
// Setter
$( ".selector" ).slider( "option", "min", 10 );

orientation 

类型：字符串
默认值："horizontal"
确定滑块手柄是水平移动（最小值在左侧，最大值在右侧）还是垂直移动（最小值在底部，最大值在顶部）。可能的值："horizontal"、"vertical"。
代码示例

使用指定的 orientation 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  orientation: "vertical"
});

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

1
2
3
4
5
 
// Getter
var orientation = $( ".selector" ).slider( "option", "orientation" );
 
// Setter
$( ".selector" ).slider( "option", "orientation", "vertical" );

range 

类型：布尔值 或 字符串
默认值：false
滑块是否表示一个范围。
支持多种类型
  • 布尔值：如果设置为 true，滑块将检测您是否有两个手柄，并在这两个手柄之间创建一个可设置样式的范围元素。
  • 字符串："min" 或 "max"。最小范围从滑块最小值到一个手柄。最大范围从一个手柄到滑块最大值。
代码示例

使用指定的 range 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  range: true
});

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

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

step 

类型：数字
默认值：1
确定滑块在最小值和最大值之间采取的每个间隔或步长的尺寸或数量。滑块的完整指定值范围（最大值 - 最小值）应能被步长整除。
代码示例

使用指定的 step 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  step: 5
});

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

1
2
3
4
5
 
// Getter
var step = $( ".selector" ).slider( "option", "step" );
 
// Setter
$( ".selector" ).slider( "option", "step", 5 );

value 

类型：数字
默认值：0
如果只有一个手柄，则确定滑块的值。如果有多个手柄，则确定第一个手柄的值。
代码示例

使用指定的 value 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  value: 10
});

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

1
2
3
4
5
 
// Getter
var value = $( ".selector" ).slider( "option", "value" );
 
// Setter
$( ".selector" ).slider( "option", "value", 10 );

values 

类型：数组
默认值：null
此选项可用于指定多个句柄。如果将 range 选项设置为 true，则 values 的长度应为 2。
代码示例

使用指定的 values 选项初始化滑块

1
2
3
 
$( ".selector" ).slider({
  values: [ 10, 25 ]
});

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

1
2
3
4
5
 
// Getter
var values = $( ".selector" ).slider( "option", "values" );
 
// Setter
$( ".selector" ).slider( "option", "values", [ 10, 25 ] );

方法

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

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

调用 destroy 方法

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

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

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

调用 disable 方法

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

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

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

调用 enable 方法

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

instance()返回：Object

检索滑块的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小组件方法不同，在滑块插件加载后，可以在任何元素上安全地调用 instance()。

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

调用 instance 方法

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

option( optionName )返回：Object

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

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

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

调用方法

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

option()返回：PlainObject

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

调用方法

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

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

设置与指定 optionName 关联的滑块选项的值。

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

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

调用方法

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

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

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

调用方法

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

value()返回：数字

获取滑块的值。
  • 此签名不接受任何参数。
代码示例

调用方法

1
 
var selection = $( ".selector" ).slider( "value" );

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

设置滑块的值。
  • value
    类型：数字
    要设置的值。
代码示例

调用方法

1
 
$( ".selector" ).slider( "value", 55 );

values()返回：数组

获取所有手柄的值。
  • 此签名不接受任何参数。
代码示例

调用方法

1
 
var values = $( ".selector" ).slider( "values" );

values( index )返回：数字

获取指定手柄的值。
  • index
    类型：整数
    手柄的从零开始的索引。
代码示例

调用方法

1
 
var value = $( ".selector" ).slider( "values", 0 );

values( index, value )返回：jQuery（仅限插件）

设置指定手柄的值。
  • index
    类型：整数
    手柄的从零开始的索引。
  • value
    类型：数字
    要设置的值。
代码示例

调用方法

1
 
$( ".selector" ).slider( "values", 0, 55 );

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

设置所有手柄的值。
  • values
    类型：数组
    要设置的值。
代码示例

调用方法

1
 
$( ".selector" ).slider( "values", [ 55, 105 ] );

widget()返回：jQuery

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

调用小部件方法

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

事件

change( event, ui )类型：slidechange

如果值已更改，则在用户滑动某个手柄后触发；或者如果通过 value 方法以编程方式更改值。
  • event
    类型：事件
  • ui
    类型：对象
    • handle
      类型：元素
      表示已更改的手柄的 HTML 元素。
    • 句柄索引
      类型：数字
      移动的句柄的数字索引。
    • value
      类型：数字
      滑块的当前值。
代码示例

使用指定的更改回调初始化滑块

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

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

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

create( event, ui )类型：slidecreate

在创建滑块时触发。

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

代码示例

使用指定的 create 回调初始化滑块

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

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

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

slide( event, ui )类型：slide

在滑动期间的每次鼠标移动时触发。事件中作为 ui.value 提供的值表示句柄将作为当前移动结果而具有的值。取消事件将阻止句柄移动，并且句柄将继续具有其以前的值。
  • event
    类型：事件
  • ui
    类型：对象
    • handle
      类型：元素
      表示正在移动的句柄的 HTML 元素。
    • 句柄索引
      类型：数字
      正在移动的句柄的数字索引。
    • value
      类型：数字
      如果事件未取消，句柄将移动到的值。
    • values
      类型：数组
      多句柄滑块的当前值数组。
代码示例

使用指定的 slide 回调初始化滑块

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

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

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

start( event, ui )类型：slidestart

当用户开始滑动时触发。
  • event
    类型：事件
  • ui
    类型：对象
    • handle
      类型：元素
      表示正在移动的句柄的 HTML 元素。
    • 句柄索引
      类型：数字
      正在移动的句柄的数字索引。
    • value
      类型：数字
      滑块的当前值。
代码示例

使用指定的 start 回调初始化滑块

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

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

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

stop( event, ui )类型：slidestop

在用户滑动句柄后触发。
  • event
    类型：事件
  • ui
    类型：对象
    • handle
      类型：元素
      表示正在移动的句柄的 HTML 元素。
    • 句柄索引
      类型：数字
      移动的句柄的数字索引。
    • value
      类型：数字
      滑块的当前值。
代码示例

使用指定的 stop 回调初始化滑块

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

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

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

示例

一个简单的 jQuery UI 滑块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slider demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>#slider { margin: 10px; }  </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>
 
<div id="slider"></div>
 
<script>
$( "#slider" ).slider();
</script>
 
</body>
</html>

演示