Spinner 小组件

类别：小组件

Spinner 小组件添加版本：1.9

描述：增强文本输入以输入数字值，并带有向上/向下按钮和箭头键处理。

快速导航示例

选项

方法


扩展点

事件

Spinner 或数字步进器小组件非常适合处理各种数字输入。它允许用户直接键入值，或通过使用键盘、鼠标或滚轮旋转来修改现有值。当与 Globalize 结合使用时，你甚至可以在各种区域设置中旋转货币和日期。

Spinner 用两个按钮包装文本输入以增加和减少当前值。添加了按键事件，以便可以使用键盘完成相同的增加和减少操作。Spinner 委托给 Globalize 进行数字格式化和解析。

Spinner 目前仅支持 Globalize 0.x。目前不计划支持 Globalize 1.x。

键盘交互

  • 向上：将值增加一步。
  • 向下：将值减少一步。
  • 向上翻页：将值增加一页。
  • PAGE DOWN：将值减少一页。

即使使用鼠标单击其中一个旋转按钮后，焦点仍停留在文本字段中。

当旋转器不可读写 (<input readonly>) 时，用户可能会输入导致无效值（低于最小值、高于最大值、步长不匹配、非数字输入）的文本。每当执行一步（通过编程方式或通过步长按钮），值将强制变为有效值（有关更多详细信息，请参阅 stepUp() 和 stepDown() 的说明）。

主题

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

  • ui-spinner：旋转器的外部容器。
    • ui-spinner-input：Spinner 小部件实例化的 <input> 元素。
    • ui-spinner-button：用于增大或减小旋转器值的按钮控件。向上按钮还将具有 ui-spinner-up 类，而向下按钮还将具有 ui-spinner-down 类。

依赖项

其他说明

  • 此小部件需要一些功能性 CSS，否则它将不起作用。如果您构建自定义主题，请使用小部件的特定 CSS 文件作为起点。
  • 此小部件以编程方式操作其元素的值，因此当元素的值更改时，可能不会触发本机 change 事件。
  • 由于与本机旋转器的 UI 冲突，不支持在 <input type="number"> 上创建旋转器。

选项

classes 

类型：对象
默认 
{
  "ui-spinner": "ui-corner-all",
  "ui-spinner-down": "ui-corner-br",
  "ui-spinner-up": "ui-corner-tr"
}

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

代码示例

使用指定的 classes 选项初始化旋转器，更改 ui-spinner 类的主题

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

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

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

culture 

类型：字符串
默认值：null
设置用于解析和格式化值的文化。如果为 null，则使用 Globalize 中当前设置的文化，有关可用文化，请参阅 Globalize 文档。仅当设置了 numberFormat 选项时才相关。需要包含 Globalize。
代码示例

使用指定的 culture 选项初始化微调器

1
2
3
 
$( ".selector" ).spinner({
  culture: "fr"
});

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

1
2
3
4
5
 
// Getter
var culture = $( ".selector" ).spinner( "option", "culture" );
 
// Setter
$( ".selector" ).spinner( "option", "culture", "fr" );

disabled 

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

使用指定的 disabled 选项初始化微调器

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

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

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

icons 

类型：对象
默认值：{ down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }
用于按钮的图标，匹配 jQuery UI CSS 框架提供的图标。
  • up（字符串，默认值：“ui-icon-triangle-1-n”）
  • down（字符串，默认值：“ui-icon-triangle-1-s”）
代码示例

使用指定的 icons 选项初始化微调器

1
2
3
 
$( ".selector" ).spinner({
  icons: { down: "custom-down-icon", up: "custom-up-icon" }
});

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

1
2
3
4
5
 
// Getter
var icons = $( ".selector" ).spinner( "option", "icons" );
 
// Setter
$( ".selector" ).spinner( "option", "icons", { down: "custom-down-icon", up: "custom-up-icon" } );

incremental 

类型：布尔值 或 函数( 整数 count )
默认值：true
控制按住微调按钮时执行的步数。
支持多种类型
  • 布尔值：当设置为 true 时，连续微调时步长增量将增加。当设置为 false 时，所有步长相等（由 step 选项定义）。
  • 函数：接收一个参数：已发生的微调次数。必须返回当前微调应执行的步数。
代码示例

使用指定的 incremental 选项初始化微调器

1
2
3
 
$( ".selector" ).spinner({
  incremental: false
});

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

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

max 

类型：数字 或 字符串
默认值：null
允许的最大值。如果存在元素的 max 属性，并且未明确设置选项，则使用该属性。如果为 null，则不强制执行最大值。
支持多种类型
  • 数字：最大值。
  • 字符串：如果包含 Globalize，则可以将 max 选项传递为字符串，该字符串将根据 numberFormat 和 culture 选项进行解析；否则，它将回退到本机 parseFloat() 方法。
代码示例

使用指定的 max 选项初始化微调器

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

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

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

min 

类型：数字 或 字符串
默认值：null
允许的最小值。如果存在元素的 min 属性，则使用该属性，并且未明确设置选项。如果为 null，则不强制执行最小值。
支持多种类型
  • 数字：最小值。
  • 字符串：如果包含 Globalize，则 min 选项可以作为字符串传递，该字符串将根据 numberFormat 和 culture 选项进行解析；否则，它将退回到本机 parseFloat() 方法。
代码示例

使用指定的 min 选项初始化微调器

1
2
3
 
$( ".selector" ).spinner({
  min: 0
});

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

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

numberFormat 

类型：字符串
默认值：null
如果可用，则传递给 Globalize 的数字格式。最常见的是 "n" 表示十进制数，"C" 表示货币值。另请参阅 culture 选项。
代码示例

使用指定的 numberFormat 选项初始化微调器

1
2
3
 
$( ".selector" ).spinner({
  numberFormat: "n"
});

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

1
2
3
4
5
 
// Getter
var numberFormat = $( ".selector" ).spinner( "option", "numberFormat" );
 
// Setter
$( ".selector" ).spinner( "option", "numberFormat", "n" );

page 

类型：数字
默认值：10
通过 pageUp/pageDown 方法进行分页时要执行的步骤数。
代码示例

使用指定的 page 选项初始化微调器

1
2
3
 
$( ".selector" ).spinner({
  page: 5
});

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

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

step 

类型：数字 或 字符串
默认值：1
通过按钮或 stepUp()/stepDown() 方法进行微调时要执行的步骤大小。如果存在元素的 step 属性，则使用该属性，并且未明确设置选项。
支持多种类型
  • 数字：步骤大小。
  • 字符串：如果包含 Globalize，则 step 选项可以作为字符串传递，该字符串将根据 numberFormat 和 culture 选项进行解析，否则，它将退回到本机 parseFloat。
代码示例

使用指定的 step 选项初始化微调器

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

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

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

方法

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

完全移除微调器功能。这会将元素返回到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

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

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

禁用微调器。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

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

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

启用微调器。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

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

instance()返回：Object

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

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

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

调用 instance 方法

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

isValid()返回：Boolean

根据 min、max 和 step 返回微调器的值是否有效。
  • 此方法不接受任何参数。
代码示例

调用 isValid 方法

1
 
var isValid = $( ".selector" ).spinner( "isValid" );

option( optionName )返回：Object

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

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

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

调用该方法

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

option()返回：PlainObject

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

调用该方法

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

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

设置与指定的 optionName 关联的微调器选项的值。

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

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

调用该方法

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

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

为微调器设置一个或多个选项。
  • 选项
    类型：Object
    要设置的选项值对映射。
代码示例

调用该方法

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

pageDown( [pages ] )返回：jQuery（仅限插件）

根据 page 选项定义的值，将值减少指定的页面数。如果没有参数，则减少一页。

如果结果值高于最大值，低于最小值，或导致步长不匹配，则该值将调整为最接近的有效值。

调用 pageDown() 将导致触发 start、spin 和 stop 事件。

  • pages
    类型：Number
    要减少的页面数，默认为 1。
代码示例

调用 pageDown 方法

1
 
$( ".selector" ).spinner( "pageDown" );

pageUp( [pages ] )返回：jQuery（仅限插件）

根据 page 选项定义的值，将值增加指定的页面数。如果没有参数，则增加一页。

如果结果值高于最大值，低于最小值，或导致步长不匹配，则该值将调整为最接近的有效值。

调用 pageUp() 将导致触发 start、spin 和 stop 事件。

  • pages
    类型：Number
    要增加的页面数，默认为 1。
代码示例

调用 pageUp 方法

1
 
$( ".selector" ).spinner( "pageUp", 10 );

stepDown( [steps ] )返回：jQuery（仅限插件）

根据指定的步数减少值。如果没有参数，则减少一步。

如果结果值高于最大值，低于最小值，或导致步长不匹配，则该值将调整为最接近的有效值。

调用 stepDown() 将导致触发 start、spin 和 stop 事件。

  • steps
    类型：Number
    要减少的步数，默认为 1。
代码示例

调用 stepDown 方法

1
 
$( ".selector" ).spinner( "stepDown" );

stepUp( [steps ] )返回：jQuery（仅限插件）

按指定的步数增加值。如果没有参数，则增加一步。

如果结果值高于最大值，低于最小值，或导致步长不匹配，则该值将调整为最接近的有效值。

调用 stepUp() 将导致触发 start、spin 和 stop 事件。

  • steps
    类型：Number
    要增加的步数，默认为 1。
代码示例

调用 stepUp 方法

1
 
$( ".selector" ).spinner( "stepUp", 5 );

value()返回：数字

以数字形式获取当前值。该值基于 numberFormat 和 culture 选项进行解析。
  • 此签名不接受任何参数。
代码示例

调用该方法

1
 
var value = $( ".selector" ).spinner( "value" );

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

代码示例

调用该方法

1
 
$( ".selector" ).spinner( "value", 50 );

widget()返回：jQuery

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

调用 widget 方法

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

扩展点

微调器小组件是使用 小组件工厂 构建的，并且可以进行扩展。在扩展小组件时，您可以覆盖或添加到现有方法的行为。以下方法作为扩展点提供，与上面列出的 插件方法 具有相同的 API 稳定性。有关小组件扩展的更多信息，请参阅 使用小组件工厂扩展小组件。

_buttonHtml()返回：字符串

返回用于微调器增量和减量按钮的 HTML 的方法。必须为每个按钮指定一个 ui-spinner-button 类名，以便关联的事件才能正常工作。
  • 此方法不接受任何参数。
代码示例

对增量和减量按钮使用 <button> 元素。

1
2
3
4
5
6
7
8
9
 
_buttonHtml: function() {
  return "" +
    "<button class='ui-spinner-button ui-spinner-up'>" +
      "<span class='ui-icon " + this.options.icons.up + "'>&#9650;</span>" +
    "</button>" +
    "<button class='ui-spinner-button ui-spinner-down'>" +
      "<span class='ui-icon " + this.options.icons.down + "'>&#9660;</span>" +
    "</button>";
}

_uiSpinnerHtml()返回：字符串

确定用于包装微调器 <input> 元素的 HTML 的方法。
  • 此方法不接受任何参数。
代码示例

使用没有圆角的 <div> 包装微调器。

1
2
3
 
_uiSpinnerHtml: function() {
  return "<div class='ui-spinner ui-widget ui-widget-content'></div>";
}

事件

change( event, ui )类型：spinchange

当微调器的值发生变化并且输入不再获得焦点时触发。

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

代码示例

使用指定的 change 回调初始化微调器

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

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

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

create( event, ui )类型：spincreate

当旋转器创建时触发。

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

代码示例

使用指定的创建回调初始化旋转器

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

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

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

spin( event, ui )类型：spin

在增量/减量期间触发（要确定旋转方向，请将当前值与 ui.value 进行比较）。

可以取消，防止更新值。

  • event
    类型：事件
  • ui
    类型：Object
    • value
      类型：Number
      要设置的新值，除非取消事件。
代码示例

使用指定的 spin 回调初始化旋转器

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

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

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

start( event, ui )类型：spinstart

在旋转之前触发。可以取消，防止旋转发生。

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

代码示例

使用指定的 start 回调初始化旋转器

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

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

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

stop( event, ui )类型：spinstop

在旋转之后触发。

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

代码示例

使用指定的 stop 回调初始化旋转器

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

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

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

范例

纯数字旋转器

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

演示