Spinner Widget · jQuery UI API 中文文檔 1.10

# 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> ```