Spinner Widget

Categories: Widgets

Spinner Widgetversion added: 1.9

Description: 通过向上/向下按钮和箭头按键操作，增强文本输入框的数值输入功能。

QuickNavExamples

Options

Methods


Extension Points

Events

spinner（微调组件），或数步进控件（number stepper widget），是用于处理各种数字输入的完美控件。它允许用户直接输入一个值，或通过键盘、鼠标、滚轮微调改变一个已有的值。当与全球化（Globalize）结合时，您甚至可以微调显示不同地区的货币和日期。

spinner（微调组件）使用两个按钮将文本输入覆盖为当前值的递增值和递减值。spinner（微调组件）增加了按键事件，以便可以用键盘完成相同的递增和递减。spinner（微调组件）代表 全球化（Globalize）的数字格式和解析。

键盘交互（Keyboard interaction）

  • UP：对值增加一步。
  • DOWN：对值减少一步。
  • PAGE UP：对值增加一页。
  • PAGE DOWN：对值减少一页。

用鼠标点击微调按钮后，焦点仍停留在文本域中。

当spinner（微调组件）不是只读（<input readonly>）时，用户可以输入值，这可能会产生无效的值（小于最小值，大于最大值，增减错配，非数字输入）。当增减时，不管通过编程方式还是微调按钮方式，值都会被强制为一个有效值（如需了解详情，请查看 stepUp() 和 stepDown() 的描述。

主题（Theming）

spinner（微调组件）使用 jQuery UI CSS 框架 来定义它的外观和感观的样式。如果需要使用spinner（微调组件）指定的样式，则可以使用下面的 CSS class 名称：

  • ui-spinner：spinner（微调组件）的外层容器。
    • ui-spinner-input：spinner（微调组件）实例化的 <input> 元素。
    • ui-spinner-button：用于递增或递减spinner（微调组件）值的按钮控件。向上按钮会另外带有一个 ui-spinner-up class，向下按钮会另外带有一个 ui-spinner-down class。

依赖（Dependencies）

Additional Notes:

  • 该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。
  • 该部件以编程方式操作元素的值，因此当元素的值改变时不会触发原生的 change 事件。
  • 不支持在 <input type="number"> 上创建选择器，因为会造成与本地spinner（微调组件）的 UI 冲突。

Options

cultureType: String

Default: null
设置culture选项 用于解析和格式化值。 如果为null，在Globalize下当前设置的culture将被使用， 可供的culture，请查看Globalize 文档。 只有当numberFormat选项设置了，才会有关联。 需要引用Globalize。
Code examples:

初始化带有指定 culture选项的 spinner：

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

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

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

disabledType: Boolean

Default: false
如果设置为 true，则禁用该 spinner（微调组件）。
Code examples:

初始化带有指定 disabled选项的 spinner：

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

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

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

iconsType: Object

Default: { down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }
标题要使用的图标，与 jQuery UI CSS 框架提供的图标（Icons） 匹配。设置为 false 则不显示图标。
  • up (string, default: "ui-icon-triangle-1-n")
  • down (string, default: "ui-icon-triangle-1-s")
Code examples:

初始化带有指定 icons选项的 spinner：

1
 
$( ".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" } );

incrementalType: Boolean or Function( Integer count )

Default: true
当按住spinner（微调组件）按钮不放时，控制的步数。
支持多个类型：
  • Boolean:如果设置为true，当按住spinner（微调组件）按钮不放时，数值会根据step选项的值不断的增加或减少。 当设置为false时，所有步骤都是相等的，（由step选项所定义）（注：点一下，数值会根据step选项的值增加或减少一步）。
  • Function: 接收一个参数： 已发生的自旋数。 必须返回在当前发生的微调的步数。
Code examples:

初始化带有指定 incremental选项的 spinner：

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

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

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

maxType: Number or String

Default: null
允许的最大值。 如果元素的max属性存在，该选项未明确设置，那么该元素的max属性就被用作该选项的值。 如果为null，表示没有上限。
支持多个类型：
  • Number: 最大值。
  • String: 如果应用包含了Globalize， max选项可以传递可以被 numberFormat和culture选项解析的 字符串。 否则求助原生的parseFloat()将方法。
Code examples:

初始化带有指定 max选项的 spinner：

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

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

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

minType: Number or String

Default: null
允许的最小值。 如果元素的min属性存在，该选项未明确设置，那么该元素的min属性就被用作该选项的值。 如果为null，表示没有下限。
支持多个类型：
  • Number: 最小值。
  • String: 如果应用包含了Globalize， max选项可以传递可以被 numberFormat和culture选项解析的 字符串。 否则使用原生的parseFloat()方法解析。
Code examples:

初始化带有指定 min选项的 spinner：

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

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

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

numberFormatType: String

Default: null
通过Globalize格式化数字， 如果有效的话。 最常见的用于"n"用作十进制数 和"C"用作货币值。 也看到了culture选择。
Code examples:

初始化带有指定 numberFormat选项的 spinner：

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

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

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

pageType: Number

Default: 10
当通过pageUp/pageDown的方法进行分页时，采取的步数。
Code examples:

初始化带有指定 page选项的 spinner：

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

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

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

stepType: Number or String

Default: 1
通过按钮或stepUp()/stepDown()方法微调时，采取的步数。 如果元素的step属性存在，并且该选项未明确设置，那么元素的step属性值将作为该选项的值使用。
支持多个类型：
  • Number: 步数
  • String: 如果应用包含了Globalize， max选项可以传递可以被 numberFormat和culture选项解析的 字符串。 否则使用原生的parseFloat()方法解析。
Code examples:

初始化带有指定 step选项的 spinner：

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

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

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

Methods

destroy()Returns: jQuery (plugin only)

完全移除 spinner功能。这会把元素返回到它的预初始化状态。
  • 该方法不接受任何参数。
Code examples:

调用 destroy 方法：

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

disable()Returns: jQuery (plugin only)

禁用 spinner.
  • 该方法不接受任何参数。
Code examples:

调用 disable 方法：

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

enable()Returns: jQuery (plugin only)

启用 spinner.
  • 该方法不接受任何参数。
Code examples:

调用 enable 方法：

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

option( optionName )Returns: Object

获取当前与指定的 optionName 关联的值。
  • optionName
    Type: String
    要获取值的选项的名称。
Code examples:

调用该方法：

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

option()Returns: PlainObject

获取一个包含键/值对的对象，键/值对表示当前 spinner 选项哈希。
  • 该方法不接受任何参数。
Code examples:

调用该方法：

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

option( optionName, value )Returns: jQuery (plugin only)

设置与指定的 optionName 关联的 spinner 选项的值。
  • optionName
    Type: String
    要设置的选项的名称。
  • value
    Type: Object
    要为选项设置的值。
Code examples:

调用该方法：

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

option( options )Returns: jQuery (plugin only)

为 spinner 设置一个或多个选项。
  • options
    Type: Object
    要设置的 option-value 对。
Code examples:

调用该方法：

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

pageDown( [pages ] )Returns: jQuery (plugin only)

通过指定页数递减值， 页数由page选项定义。 如果没有参数， 单页递减。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配， 那么该值将被调整到最接近的有效值。

调用pageDown()将引起start, spin, 和 stop 事件被触发。

  • pages
    Type: Number
    递减的页数，默认是1.
Code examples:

调用 pageDown 方法：

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

pageUp( [pages ] )Returns: jQuery (plugin only)

通过指定页数递增值， 页数由page选项定义。 如果没有参数， 单页递增。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配， 那么该值将被调整到最接近的有效值。

调用pageUp()将引起start, spin, 和 stop 事件被触发。

  • pages
    Type: Number
    递增的页数，默认是1.
Code examples:

调用 pageUp 方法：

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

stepDown( [steps ] )Returns: jQuery (plugin only)

通过指定步数递减值， 步数由step选项定义。 如果没有参数， 单步递减。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配， 那么该值将被调整到最接近的有效值。

调用stepDown()将引起start, spin, 和 stop 事件被触发。

  • steps
    Type: Number
    递减的步数，默认是1.
Code examples:

调用 stepDown 方法：

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

stepUp( [steps ] )Returns: jQuery (plugin only)

通过指定步数递增值， 步数由step选项定义。 如果没有参数， 单步递增。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配， 那么该值将被调整到最接近的有效值。

调用pageUp()将引起start, spin, 和 stop 事件被触发。

  • steps
    Type: Number
    递增的步数，默认是1.
Code examples:

调用 stepUp 方法：

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

value()Returns: Number

获取当前数值，这个值是基于numberFormat 和 culture选项解析的。
  • 该方法不接受任何参数。
Code examples:

调用该方法：

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

value( value )Returns: jQuery (plugin only)

设置当前值
  • value
    Type: Number or String
    用来设置的值。 如果传递的是一个字符串，那么 这个值是基于numberFormat 和 culture选项解析的。
Code examples:

调用该方法：

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

widget()Returns: jQuery

返回包含生成组件包裹元素 的一个jQuery对象。
  • 该方法不接受任何参数。
Code examples:

调用 widget 方法：

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

扩展点（Extension Points）

spinner（微调组件）是widget factory构建的，并且可以扩展。 当扩展部件时， 你必须覆盖或添加新的行为到现有的方法。 下列方法被提供作为扩展点 用相同的API稳定性如上所列的plugin methods。 有关小部件扩展的更多信息， 请参阅使用Widget Factory 扩展小部件。

_buttonHtml()Returns: String

这个方法返回的HTML用于spinner（微调组件）的递增和递减按钮。 每个按钮都必须给定一个ui-spinner-button的类名 用于相关联的事件工作。
  • 该方法不接受任何参数。
Code examples:

使用<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()Returns: String

这个方法返回的HTML用于包裹 spinner（微调组件）<input>元素。
  • 该方法不接受任何参数。
Code examples:

用没有圆角的<div> 包裹 spinner（微调组件）。

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

Events

change( event, ui )Type: spinchange

当spinner微调器的值改变并且输入元素（input）失去焦点时，该事件触发。

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 change 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spinchange 事件：

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

create( event, ui )Type: spincreate

当spinner微调器创建的时候，该时间触发。

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 create 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spincreate 事件：

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

spin( event, ui )Type: spin

在递增/递减的时候，该事件触发（用 当前值和ui.value比较来 确定的微调的方向）。

可以取消，以防止被更新值。

  • event
    Type: Event
  • ui
    Type: Object
    • value
      Type: Number
      要设置的新值，除非该事件被取消。/div>
Code examples:

初始化带有指定 spin 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spin 事件：

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

start( event, ui )Type: spinstart

微调开始之前，触发该事件。可以取消，以防止微调。

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 start 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spinstart 事件：

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

stop( event, ui )Type: spinstop

微调结束后，触发该事件。

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 stop 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spinstop 事件：

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

Example:

普通的数字微调器。

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="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <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>
 
<input id="spinner">
 
<script>
$( "#spinner" ).spinner();
</script>
 
</body>
</html>

Demo: