ThinkChat2.0新版上线,更智能更精彩,支持会话、画图、阅读、搜索等,送10W Token,即刻开启你的AI之旅 广告
# Spinner Widget # Spinner Widget Categories: [Widgets](http://www.css88.com/jquery-ui-api/category/widgets/ "View all posts in Widgets") ## version added: 1.9 **Description:** 通过向上/向下按钮和箭头按键操作,增强文本输入框的数值输入功能。 ## QuickNav[Examples](#entry-examples) ### Options - [culture](#option-culture) - [disabled](#option-disabled) - [icons](#option-icons) - [incremental](#option-incremental) - [max](#option-max) - [min](#option-min) - [numberFormat](#option-numberFormat) - [page](#option-page) - [step](#option-step) ### Methods - [destroy](#method-destroy) - [disable](#method-disable) - [enable](#method-enable) - [option](#method-option) - [pageDown](#method-pageDown) - [pageUp](#method-pageUp) - [stepDown](#method-stepDown) - [stepUp](#method-stepUp) - [value](#method-value) - [widget](#method-widget) ### Extension Points - [\_buttonHtml](#method-_buttonHtml) - [\_uiSpinnerHtml](#method-_uiSpinnerHtml) ### Events - [change](#event-change) - [create](#event-create) - [spin](#event-spin) - [start](#event-start) - [stop](#event-stop) spinner(微调组件),或数步进控件(number stepper widget),是用于处理各种数字输入的完美控件。它允许用户直接输入一个值,或通过键盘、鼠标、滚轮微调改变一个已有的值。当与全球化(Globalize)结合时,您甚至可以微调显示不同地区的货币和日期。 spinner(微调组件)使用两个按钮将文本输入覆盖为当前值的递增值和递减值。spinner(微调组件)增加了按键事件,以便可以用键盘完成相同的递增和递减。spinner(微调组件)代表 [全球化(Globalize)](https://github.com/jquery/globalize)的数字格式和解析。 ### 键盘交互(Keyboard interaction) - UP:对值增加一步。 - DOWN:对值减少一步。 - PAGE UP:对值增加一页。 - PAGE DOWN:对值减少一页。 用鼠标点击微调按钮后,焦点仍停留在文本域中。 当spinner(微调组件)不是只读(`<input readonly>`)时,用户可以输入值,这可能会产生无效的值(小于最小值,大于最大值,增减错配,非数字输入)。当增减时,不管通过编程方式还是微调按钮方式,值都会被强制为一个有效值(如需了解详情,请查看 [`stepUp()`](#method-stepUp) 和 [`stepDown()`](#method-stepDown) 的描述。 ### 主题(Theming) spinner(微调组件)使用 [jQuery UI CSS 框架](theming/css-framework) 来定义它的外观和感观的样式。如果需要使用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)](category/ui-core) - [部件库(Widget Factory)](jQuery.widget) - [按钮部件(Button Widget)](button) - [全球化(Globalize)](https://github.com/jquery/globalize)(外部的,可选的;当与 [`culture`](#option-culture) 和 [`numberFormat`](#option-numberFormat) 选项一起使用时) ### Additional Notes: - 该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。 - 该部件以编程方式操作元素的值,因此当元素的值改变时不会触发原生的 `change` 事件。 - 不支持在 `<input type="number">` 上创建选择器,因为会造成与本地spinner(微调组件)的 UI 冲突。 ## Options ### culture**Type:** [String](http://api.jquery.com/Types/#String) **Default:**`null`设置`culture`选项 用于解析和格式化值。 如果为`null`,在`Globalize`下当前设置的culture将被使用, 可供的`culture`,请查看[Globalize 文档](https://github.com/jquery/globalize)。 只有当[`numberFormat`](#option-numberFormat)选项设置了,才会有关联。 需要引用[Globalize](https://github.com/jquery/globalize)。**Code examples:** 初始化带有指定 `culture`选项的 spinner: ``` $( ".selector" ).spinner({ culture: "fr" }); ``` 在初始化后,获取或设置`culture` 选项: ``` // getter var culture = $( ".selector" ).spinner( "option", "culture" ); // setter $( ".selector" ).spinner( "option", "culture", "fr" ); ``` ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#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 ); ``` ### icons**Type:** [Object](http://api.jquery.com/Types/#Object) **Default:**`{ down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }`标题要使用的图标,与 [jQuery UI CSS 框架提供的图标(Icons)](theming/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" } ); ``` ### incremental**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [Function](http://api.jquery.com/Types/#Function)( [Integer](http://api.jquery.com/Types/#Integer) count ) **Default:**`true`当按住spinner(微调组件)按钮不放时,控制的步数。**支持多个类型:** - **Boolean**:如果设置为`true`,当按住spinner(微调组件)按钮不放时,数值会根据[`step`](#option-step)选项的值不断的增加或减少。 当设置为`false`时,所有步骤都是相等的,(由[`step`](#option-step)选项所定义)(愚人码头注:点一下,数值会根据[`step`](#option-step)选项的值增加或减少一步)。 - **Function**: 接收一个参数: 已发生的自旋数。 必须返回在当前发生的微调的步数。 **Code examples:** 初始化带有指定 `incremental`选项的 spinner: ``` $( ".selector" ).spinner({ incremental: false }); ``` 在初始化后,获取或设置`incremental` 选项: ``` // getter var incremental = $( ".selector" ).spinner( "option", "incremental" ); // setter $( ".selector" ).spinner( "option", "incremental", false ); ``` ### max**Type:** [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) **Default:**`null`允许的最大值。 如果元素的`max`属性存在,该选项未明确设置,那么该元素的`max`属性就被用作该选项的值。 如果为`null`,表示没有上限。**支持多个类型:** - **Number**: 最大值。 - **String**: 如果应用包含了[Globalize](https://github.com/jquery/globalize), `max`选项可以传递可以被 [`numberFormat`](#opiton-numberFormat)和[`culture`](#option-culture)选项解析的 字符串。 否则求助原生的`parseFloat()`将方法。 **Code examples:** 初始化带有指定 `max`选项的 spinner: ``` $( ".selector" ).spinner({ max: 50 }); ``` 在初始化后,获取或设置`max` 选项: ``` // getter var max = $( ".selector" ).spinner( "option", "max" ); // setter $( ".selector" ).spinner( "option", "max", 50 ); ``` ### min**Type:** [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) **Default:**`null`允许的最小值。 如果元素的`min`属性存在,该选项未明确设置,那么该元素的`min`属性就被用作该选项的值。 如果为`null`,表示没有下限。**支持多个类型:** - **Number**: 最小值。 - **String**: 如果应用包含了[Globalize](https://github.com/jquery/globalize), `max`选项可以传递可以被 [`numberFormat`](#opiton-numberFormat)和[`culture`](#option-culture)选项解析的 字符串。 否则使用原生的`parseFloat()`方法解析。 **Code examples:** 初始化带有指定 `min`选项的 spinner: ``` $( ".selector" ).spinner({ min: 0 }); ``` 在初始化后,获取或设置`min` 选项: ``` // getter var min = $( ".selector" ).spinner( "option", "min" ); // setter $( ".selector" ).spinner( "option", "min", 0 ); ``` ### numberFormat**Type:** [String](http://api.jquery.com/Types/#String) **Default:**`null`通过[`Globalize`](https://github.com/jquery/globalize)格式化数字, 如果有效的话。 最常见的用于`"n"`用作十进制数 和`"C"`用作货币值。 也看到了[`culture`](#option-culture)选择。**Code examples:** 初始化带有指定 `numberFormat`选项的 spinner: ``` $( ".selector" ).spinner({ numberFormat: "n" }); ``` 在初始化后,获取或设置`numberFormat` 选项: ``` // getter var numberFormat = $( ".selector" ).spinner( "option", "numberFormat" ); // setter $( ".selector" ).spinner( "option", "numberFormat", "n" ); ``` ### page**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:**`10`当通过[`pageUp`](#method-pageUp)/[`pageDown`](#method-pageDown)的方法进行分页时,采取的步数。**Code examples:** 初始化带有指定 `page`选项的 spinner: ``` $( ".selector" ).spinner({ page: 5 }); ``` 在初始化后,获取或设置`page` 选项: ``` // getter var page = $( ".selector" ).spinner( "option", "page" ); // setter $( ".selector" ).spinner( "option", "page", 5 ); ``` ### step**Type:** [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) **Default:**`1`通过按钮或[`stepUp()`](#method-stepUp)/[`stepDown()`](#method-stepDown)方法微调时,采取的步数。 如果元素的`step`属性存在,并且该选项未明确设置,那么元素的`step`属性值将作为该选项的值使用。**支持多个类型:** - **Number**: 步数 - **String**: 如果应用包含了[Globalize](https://github.com/jquery/globalize), `max`选项可以传递可以被 [`numberFormat`](#opiton-numberFormat)和[`culture`](#option-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](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 完全移除 spinner功能。这会把元素返回到它的预初始化状态。 - 该方法不接受任何参数。 **Code examples:** 调用 destroy 方法: ``` $( ".selector" ).spinner( "destroy" ); ``` ### disable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 禁用 spinner. - 该方法不接受任何参数。 **Code examples:** 调用 disable 方法: ``` $( ".selector" ).spinner( "disable" ); ``` ### enable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 启用 spinner. - 该方法不接受任何参数。 **Code examples:** 调用 enable 方法: ``` $( ".selector" ).spinner( "enable" ); ``` ### option( optionName )Returns: [Object](http://api.jquery.com/Types/#Object) 获取当前与指定的 `optionName` 关联的值。 - **optionName**Type: [String](http://api.jquery.com/Types/#String)要获取值的选项的名称。 **Code examples:** 调用该方法: ``` var isDisabled = $( ".selector" ).spinner( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 获取一个包含键/值对的对象,键/值对表示当前 spinner 选项哈希。 - 该方法不接受任何参数。 **Code examples:** 调用该方法: ``` var options = $( ".selector" ).spinner( "option" ); ``` ### option( optionName, value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 设置与指定的 `optionName` 关联的 spinner 选项的值。 - **optionName**Type: [String](http://api.jquery.com/Types/#String)要设置的选项的名称。 - **value**Type: [Object](http://api.jquery.com/Types/#Object)要为选项设置的值。 **Code examples:** 调用该方法: ``` $( ".selector" ).spinner( "option", "disabled", true ); ``` ### option( options )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 为 spinner 设置一个或多个选项。 - **options**Type: [Object](http://api.jquery.com/Types/#Object)要设置的 option-value 对。 **Code examples:** 调用该方法: ``` $( ".selector" ).spinner( "option", { disabled: true } ); ``` ### pageDown( \[pages \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 通过指定页数递减值, 页数由[`page`](#option-page)选项定义。 如果没有参数, 单页递减。 如果返回值大于[`max`](#option-max)选项定义的值,小于[`min`](#option-min)选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。 调用`pageDown()`将引起[`start`](#event-start), [`spin`](#event-spin), 和 [`stop`](#event-stop) 事件被触发。 - **pages**Type: [Number](http://api.jquery.com/Types/#Number)递减的页数,默认是1. **Code examples:** 调用 pageDown 方法: ``` $( ".selector" ).spinner( "pageDown" ); ``` ### pageUp( \[pages \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 通过指定页数递增值, 页数由[`page`](#option-page)选项定义。 如果没有参数, 单页递增。 如果返回值大于[`max`](#option-max)选项定义的值,小于[`min`](#option-min)选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。 调用`pageUp()`将引起[`start`](#event-start), [`spin`](#event-spin), 和 [`stop`](#event-stop) 事件被触发。 - **pages**Type: [Number](http://api.jquery.com/Types/#Number)递增的页数,默认是1. **Code examples:** 调用 pageUp 方法: ``` $( ".selector" ).spinner( "pageUp", 10 ); ``` ### stepDown( \[steps \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 通过指定步数递减值, 步数由[`step`](#option-step)选项定义。 如果没有参数, 单步递减。 如果返回值大于[`max`](#option-max)选项定义的值,小于[`min`](#option-min)选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。 调用`stepDown()`将引起[`start`](#event-start), [`spin`](#event-spin), 和 [`stop`](#event-stop) 事件被触发。 - **steps**Type: [Number](http://api.jquery.com/Types/#Number)递减的步数,默认是1. **Code examples:** 调用 stepDown 方法: ``` $( ".selector" ).spinner( "stepDown" ); ``` ### stepUp( \[steps \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 通过指定步数递增值, 步数由[`step`](#option-step)选项定义。 如果没有参数, 单步递增。 如果返回值大于[`max`](#option-max)选项定义的值,小于[`min`](#option-min)选项定义的值,或返回的结果步数不匹配, 那么该值将被调整到最接近的有效值。 调用`pageUp()`将引起[`start`](#event-start), [`spin`](#event-spin), 和 [`stop`](#event-stop) 事件被触发。 - **steps**Type: [Number](http://api.jquery.com/Types/#Number)递增的步数,默认是1. **Code examples:** 调用 stepUp 方法: ``` $( ".selector" ).spinner( "stepUp", 5 ); ``` ### value()Returns: [Number](http://api.jquery.com/Types/#Number) 获取当前数值,这个值是基于[`numberFormat`](#option-numberFormat) 和 [`culture`](#option-culture)选项解析的。 - 该方法不接受任何参数。 **Code examples:** 调用该方法: ``` var value = $( ".selector" ).spinner( "value" ); ``` ### value( value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 设置当前值 - **value**Type: [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String)用来设置的值。 如果传递的是一个字符串,那么 这个值是基于[`numberFormat`](#option-numberFormat) 和 [`culture`](#option-culture)选项解析的。 **Code examples:** 调用该方法: ``` $( ".selector" ).spinner( "value", 50 ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回包含生成组件包裹元素 的一个`jQuery`对象。 - 该方法不接受任何参数。 **Code examples:** 调用 widget 方法: ``` var widget = $( ".selector" ).spinner( "widget" ); ``` ## 扩展点(Extension Points) spinner(微调组件)是[widget factory](http://www.css88.com/jquery-ui-api/jQuery.widget/)构建的,并且可以扩展。 当扩展部件时, 你必须覆盖或添加新的行为到现有的方法。 下列方法被提供作为扩展点 用相同的API稳定性如上所列的[plugin methods](#methods)。 有关小部件扩展的更多信息, 请参阅[使用Widget Factory 扩展小部件](http://learn.jquery.com/jquery-ui/widget-factory/extending-widgets/)。 ### \_buttonHtml()Returns: [String](http://api.jquery.com/Types/#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](http://api.jquery.com/Types/#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)失去焦点时,该事件触发。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) *注意:`ui` 对象是空的,这里包含它是为了与其他事件保持一致性。* **Code examples:** 初始化带有指定 change 回调的 spinner(微调器): ``` $( ".selector" ).spinner({ change: function( event, ui ) {} }); ``` 绑定一个事件监听器到 spinchange 事件: ``` $( ".selector" ).on( "spinchange", function( event, ui ) {} ); ``` ### create( event, ui )Type: `spincreate` 当spinner微调器创建的时候,该时间触发。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) *注意:`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`比较来 确定的微调的方向)。 可以取消,以防止被更新值。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) - **value**Type: [Number](http://api.jquery.com/Types/#Number)要设置的新值,除非该事件被取消。/div> **Code examples:** 初始化带有指定 spin 回调的 spinner(微调器): ``` $( ".selector" ).spinner({ spin: function( event, ui ) {} }); ``` 绑定一个事件监听器到 spin 事件: ``` $( ".selector" ).on( "spin", function( event, ui ) {} ); ``` ### start( event, ui )Type: `spinstart` 微调开始之前,触发该事件。可以取消,以防止微调。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) *注意:`ui` 对象是空的,这里包含它是为了与其他事件保持一致性。* **Code examples:** 初始化带有指定 start 回调的 spinner(微调器): ``` $( ".selector" ).spinner({ start: function( event, ui ) {} }); ``` 绑定一个事件监听器到 spinstart 事件: ``` $( ".selector" ).on( "spinstart", function( event, ui ) {} ); ``` ### stop( event, ui )Type: `spinstop` 微调结束后,触发该事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) *注意:`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> ```