Spinner Widget · jQuery UI API 中文文檔

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