Spinner Widget
Categories: Widgets
version 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)
- UI 核心(UI Core)
- 部件库(Widget Factory)
- 按钮部件(Button Widget)
- 全球化(Globalize)(外部的,可选的;当与
culture
和numberFormat
选项一起使用时)
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:
$( ".selector" ).spinner({ culture: "fr" });
在初始化后,获取或设置culture
选项:
// getter
var culture = $( ".selector" ).spinner( "option", "culture" );
// setter
$( ".selector" ).spinner( "option", "culture", "fr" );
disabledType: Boolean
Default: false
如果设置为 true
,则禁用该 spinner(微调组件)。Code examples:
初始化带有指定 disabled
选项的 spinner:
$( ".selector" ).spinner({ disabled: true });
在初始化后,获取或设置disabled
选项:
// 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:
$( ".selector" ).spinner({ icons: { down: "custom-down-icon", up: "custom-up-icon" } });
在初始化后,获取或设置icons
选项:
// 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:
$( ".selector" ).spinner({ incremental: false });
在初始化后,获取或设置incremental
选项:
// 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:
$( ".selector" ).spinner({ max: 50 });
在初始化后,获取或设置max
选项:
// 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:
$( ".selector" ).spinner({ min: 0 });
在初始化后,获取或设置min
选项:
// 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:
$( ".selector" ).spinner({ numberFormat: "n" });
在初始化后,获取或设置numberFormat
选项:
// getter
var numberFormat = $( ".selector" ).spinner( "option", "numberFormat" );
// setter
$( ".selector" ).spinner( "option", "numberFormat", "n" );
pageType: Number
Default: 10
当通过pageUp
/pageDown
的方法进行分页时,采取的步数。Code examples:
初始化带有指定 page
选项的 spinner:
$( ".selector" ).spinner({ page: 5 });
在初始化后,获取或设置page
选项:
// 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:
$( ".selector" ).spinner({ step: 2 });
在初始化后,获取或设置step
选项:
// getter
var step = $( ".selector" ).spinner( "option", "step" );
// setter
$( ".selector" ).spinner( "option", "step", 2 );
Methods
destroy()Returns: jQuery (plugin only)
完全移除 spinner功能。这会把元素返回到它的预初始化状态。
- 该方法不接受任何参数。
Code examples:
调用 destroy 方法:
$( ".selector" ).spinner( "destroy" );
disable()Returns: jQuery (plugin only)
禁用 spinner.
- 该方法不接受任何参数。
Code examples:
调用 disable 方法:
$( ".selector" ).spinner( "disable" );
enable()Returns: jQuery (plugin only)
启用 spinner.
- 该方法不接受任何参数。
Code examples:
调用 enable 方法:
$( ".selector" ).spinner( "enable" );
option( optionName )Returns: Object
获取当前与指定的 optionName
关联的值。
- optionNameType: String要获取值的选项的名称。
Code examples:
调用该方法:
var isDisabled = $( ".selector" ).spinner( "option", "disabled" );
option()Returns: PlainObject
获取一个包含键/值对的对象,键/值对表示当前 spinner 选项哈希。
- 该方法不接受任何参数。
Code examples:
调用该方法:
var options = $( ".selector" ).spinner( "option" );
option( optionName, value )Returns: jQuery (plugin only)
设置与指定的 optionName
关联的 spinner 选项的值。
Code examples:
调用该方法:
$( ".selector" ).spinner( "option", "disabled", true );
option( options )Returns: jQuery (plugin only)
为 spinner 设置一个或多个选项。
- optionsType: Object要设置的 option-value 对。
Code examples:
调用该方法:
$( ".selector" ).spinner( "option", { disabled: true } );
pageDown( [pages ] )Returns: jQuery (plugin only)
通过指定页数递减值, 页数由page
选项定义。 如果没有参数, 单页递减。
如果返回值大于max
选项定义的值,小于min
选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。
调用pageDown()
将引起start
, spin
, 和 stop
事件被触发。
- pagesType: Number递减的页数,默认是1.
Code examples:
调用 pageDown 方法:
$( ".selector" ).spinner( "pageDown" );
pageUp( [pages ] )Returns: jQuery (plugin only)
通过指定页数递增值, 页数由page
选项定义。 如果没有参数, 单页递增。
如果返回值大于max
选项定义的值,小于min
选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。
调用pageUp()
将引起start
, spin
, 和 stop
事件被触发。
- pagesType: Number递增的页数,默认是1.
Code examples:
调用 pageUp 方法:
$( ".selector" ).spinner( "pageUp", 10 );
stepDown( [steps ] )Returns: jQuery (plugin only)
通过指定步数递减值, 步数由step
选项定义。 如果没有参数, 单步递减。
如果返回值大于max
选项定义的值,小于min
选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。
调用stepDown()
将引起start
, spin
, 和 stop
事件被触发。
- stepsType: Number递减的步数,默认是1.
Code examples:
调用 stepDown 方法:
$( ".selector" ).spinner( "stepDown" );
stepUp( [steps ] )Returns: jQuery (plugin only)
通过指定步数递增值, 步数由step
选项定义。 如果没有参数, 单步递增。
如果返回值大于max
选项定义的值,小于min
选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。
调用pageUp()
将引起start
, spin
, 和 stop
事件被触发。
- stepsType: Number递增的步数,默认是1.
Code examples:
调用 stepUp 方法:
$( ".selector" ).spinner( "stepUp", 5 );
value()Returns: Number
获取当前数值,这个值是基于numberFormat
和 culture
选项解析的。
- 该方法不接受任何参数。
Code examples:
调用该方法:
var value = $( ".selector" ).spinner( "value" );
value( value )Returns: jQuery (plugin only)
设置当前值
- valueType: Number or String用来设置的值。 如果传递的是一个字符串,那么 这个值是基于
numberFormat
和culture
选项解析的。
Code examples:
调用该方法:
$( ".selector" ).spinner( "value", 50 );
widget()Returns: jQuery
返回包含生成组件包裹元素 的一个jQuery
对象。
- 该方法不接受任何参数。
Code examples:
调用 widget 方法:
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>
元素 作为递增和递减按钮。
_buttonHtml: function() {
return "" +
"<button class='ui-spinner-button ui-spinner-up'>" +
"<span class='ui-icon " + this.options.icons.up + "'>▲</span>" +
"</button>" +
"<button class='ui-spinner-button ui-spinner-down'>" +
"<span class='ui-icon " + this.options.icons.down + "'>▼</span>" +
"</button>";
}
_uiSpinnerHtml()Returns: String
这个方法返回的HTML用于包裹 spinner(微调组件)<input>
元素。
- 该方法不接受任何参数。
Code examples:
用没有圆角的<div>
包裹 spinner(微调组件)。
_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(微调器):
$( ".selector" ).spinner({
change: function( event, ui ) {}
});
绑定一个事件监听器到 spinchange 事件:
$( ".selector" ).on( "spinchange", function( event, ui ) {} );
create( event, ui )Type: spincreate
当spinner微调器创建的时候,该时间触发。
注意:ui
对象是空的,这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 create 回调的 spinner(微调器):
$( ".selector" ).spinner({
create: function( event, ui ) {}
});
绑定一个事件监听器到 spincreate 事件:
$( ".selector" ).on( "spincreate", function( event, ui ) {} );
spin( event, ui )Type: spin
在递增/递减的时候,该事件触发(用 当前值和ui.value
比较来 确定的微调的方向)。
可以取消,以防止被更新值。
Code examples:
初始化带有指定 spin 回调的 spinner(微调器):
$( ".selector" ).spinner({
spin: function( event, ui ) {}
});
绑定一个事件监听器到 spin 事件:
$( ".selector" ).on( "spin", function( event, ui ) {} );
start( event, ui )Type: spinstart
微调开始之前,触发该事件。可以取消,以防止微调。
注意:ui
对象是空的,这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 start 回调的 spinner(微调器):
$( ".selector" ).spinner({
start: function( event, ui ) {}
});
绑定一个事件监听器到 spinstart 事件:
$( ".selector" ).on( "spinstart", function( event, ui ) {} );
stop( event, ui )Type: spinstop
微调结束后,触发该事件。
注意:ui
对象是空的,这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 stop 回调的 spinner(微调器):
$( ".selector" ).spinner({
stop: function( event, ui ) {}
});
绑定一个事件监听器到 spinstop 事件:
$( ".selector" ).on( "spinstop", function( event, ui ) {} );
Example:
普通的数字微调器。
<!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>