Spinner Widget


Spinner Widgetversion added: 1.9

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

QuickNavExamples

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: 如果应用包含了Globalizemax选项可以传递可以被 numberFormatculture选项解析的 字符串。 否则求助原生的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: 如果应用包含了Globalizemax选项可以传递可以被 numberFormatculture选项解析的 字符串。 否则使用原生的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: 如果应用包含了Globalizemax选项可以传递可以被 numberFormatculture选项解析的 字符串。 否则使用原生的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

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

调用该方法:

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

value( value )Returns: jQuery (plugin only)

设置当前值
  • value
    Type: Number or String
    用来设置的值。 如果传递的是一个字符串,那么 这个值是基于numberFormatculture选项解析的。
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: