Slider Widget · jQuery UI API 中文文檔 1.10

# Slider Widget Categories: [Widgets](http://www.css88.com/jquery-ui-api/category/widgets/ "View all posts in Widgets") ## version added: 1.5 **Description:** 拖動手柄以選擇一個數值。 ## QuickNav[Examples](#entry-examples) ### Options + [animate](#option-animate) + [disabled](#option-disabled) + [max](#option-max) + [min](#option-min) + [orientation](#option-orientation) + [range](#option-range) + [step](#option-step) + [value](#option-value) + [values](#option-values) ### Methods + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [option](#method-option) + [value](#method-value) + [values](#method-values) + [widget](#method-widget) ### Events + [change](#event-change) + [create](#event-create) + [slide](#event-slide) + [start](#event-start) + [stop](#event-stop) jQuery UI Slider 插件使所選擇的元素成為一個滑塊(slider). 可以多種選項,例如多個操作手柄和操作范圍。手柄可以被鼠標拖動或者隨著方向鍵移動。 slider小工具將在初始化的時候根據 `ui-slider-handle`樣式名創建手柄元素。您可以在初始化前通過創建和追加的方式，或者在元素上添加`ui-slider-handle` 樣式來自定義手柄元素。這只會創建需要匹配[`value`](#option-value)/[`values`](#option-values)的手柄數值個數。例如，如果您指定的`值: [ 1, 5, 18 ]`，并創建一個自定義手柄，該插件將創建另外兩個。 ### 主題(Theming) slider小工具使用[jQuery UI CSS framework](/theming/css-framework/)樣式的外觀和感覺。如果滑塊具體樣式是必須的，你可以用下面的CSS類名： * `ui-slider`: 滑塊控件的軌道。該元素將追加一個`ui-slider-horizontal` 或 `ui-slider-vertical`樣式名，這取決于slider小工具是橫向還是縱向的。另外具有UI的滑塊水平或UI滑塊垂直取決于[`orientation`](#option-orientation)參數，表示滑塊的取向的類名。 * `ui-slider-handle`: 滑塊手柄. * `ui-slider-range`: 當設置選項時使用的已選范圍。如果 [`range`](#option-range) 選項設置為 `"min"` 或者 `"max"`，則該元素會分別另外帶有一個 `ui-slider-range-min` 或 `ui-slider-range-max` 類。 ### 依賴 * [UI 核心（UI Core）](/category/ui-core/) * [部件庫（Widget Factory）](/jQuery.widget/) * [鼠標交互（Mouse Interaction）](/mouse/) ### 其他注意事項: * 該部件要求一些功能性的 CSS，否則將無法工作。如果您創建了一個自定義的主題，請使用小部件指定的 CSS 文件作為起點。 ## 選項 ### animate**類型:** [Boolean](http://api.jquery.com/Types/#Boolean) or [String](http://api.jquery.com/Types/#String) or [Number](http://api.jquery.com/Types/#Number) **默認值:** `false`當用戶單擊滑塊軌道時是否平穩地滑動手柄。也可以接受任何有效的[動畫持續時間](//api.jquery.com/animate/#duration)。**多種類型支持：** * **Boolean**: 當設置為 `true`時, 滑動手柄將以默認的持續時間執行動畫。 * **String**: 速度的名稱, 比如 `"fast"` 或 `"slow"`。 * **Number**: 動畫持續時間, 以毫秒為單位。 **代碼示例:** 使用指定`animate`選項初始化滑塊： ``` $( ".selector" ).slider({ animate: "fast" }); ``` 初始化后，獲取或者設置`animate`選項: ``` // getter var animate = $( ".selector" ).slider( "option", "animate" ); // setter $( ".selector" ).slider( "option", "animate", "fast" ); ``` ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為`true`，則禁用滑塊。**Code examples:** 使用`disabled`選項初始化滑塊組件： ``` $( ".selector" ).slider({ disabled: true }); ``` 在組件初始化之后，讀取或設置 `disabled` 選項： ``` // getter var disabled = $( ".selector" ).slider( "option", "disabled" ); // setter $( ".selector" ).slider( "option", "disabled", true ); ``` ### max**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `100`滑塊的最大值。**Code examples:** 使用`max`選項初始化滑塊組件： ``` $( ".selector" ).slider({ max: 50 }); ``` 在組件初始化之后，讀取或設置 `max` 選項： ``` // getter var max = $( ".selector" ).slider( "option", "max" ); // setter $( ".selector" ).slider( "option", "max", 50 ); ``` ### min**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `0`滑塊的最小值**Code examples:** 使用`min`選項初始化滑塊組件： ``` $( ".selector" ).slider({ min: 10 }); ``` 在組件初始化之后，讀取或設置 `min` 選項： ``` // getter var min = $( ".selector" ).slider( "option", "min" ); // setter $( ".selector" ).slider( "option", "min", 10 ); ``` ### orientation**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `"horizontal"`確定滑塊手柄將水平（最小在左，最大在右）或垂直（最小在底部，最大在頂部）移動。（愚人碼頭注：就是滑塊的方向，橫向或縱向）可能的值：`"horizontal"`（橫向）, `"vertical"`（縱向）。**Code examples:** 使用`orientation`選項初始化滑塊組件： ``` $( ".selector" ).slider({ orientation: "vertical" }); ``` 在組件初始化之后，讀取或設置 `orientation` 選項： ``` // getter var orientation = $( ".selector" ).slider( "option", "orientation" ); // setter $( ".selector" ).slider( "option", "orientation", "vertical" ); ``` ### range**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [String](http://api.jquery.com/Types/#String) **Default:** `false`滑塊是否表現為一個范圍。**多種類型支持：** * **Boolean**: 如果設置為`true`,如果你有兩個手柄，slider將會感應到他們之間各種可能的范圍要素。 * **String**: 或者他們是`"min"` 或者 `"max"`值。最小的范圍將從slider的最小值傳遞給操作柄。最大的范圍將從slider的最大值傳遞給操作柄 **Code examples:** 使用`range`選項初始化滑塊組件： ``` $( ".selector" ).slider({ range: true }); ``` 在組件初始化之后，讀取或設置 `range` 選項： ``` // getter var range = $( ".selector" ).slider( "option", "range" ); // setter $( ".selector" ).slider( "option", "range", true ); ``` ### step**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `1`定義slider從最小值移動到最大值的單位步長。在這個指定范圍(最小值到最大值)內的值需要能被范圍整除。**Code examples:** 使用`step`選項初始化滑塊組件： ``` $( ".selector" ).slider({ step: 5 }); ``` 在組件初始化之后，讀取或設置 `step` 選項： ``` // getter var step = $( ".selector" ).slider( "option", "step" ); // setter $( ".selector" ).slider( "option", "step", 5 ); ``` ### value**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `0`如果只有一個手柄則是指定slider的value值。如果有多余一個的操作柄, 則是定義第一個操作柄的value值。**Code examples:** 使用`value`選項初始化滑塊組件： ``` $( ".selector" ).slider({ value: 10 }); ``` 在組件初始化之后，讀取或設置 `value` 選項： ``` // getter var value = $( ".selector" ).slider( "option", "value" ); // setter $( ".selector" ).slider( "option", "value", 10 ); ``` ### values**Type:** [Array](http://api.jquery.com/Types/#Array) **Default:** `null`這個選項可以用來為多個操作柄設定value值. 如果 [`range`](#option-range) 設置為 `true`, 'values' 的長度最少應為 2。**Code examples:** 使用`values`選項初始化滑塊組件： ``` $( ".selector" ).slider({ values: [ 10, 25 ] }); ``` 在組件初始化之后，讀取或設置 `values` 選項： ``` // getter var values = $( ".selector" ).slider( "option", "values" ); // setter $( ".selector" ).slider( "option", "values", [ 10, 25 ] ); ``` ## Methods ### destroy()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 完全銷毀滑塊組件的功能，這將使元素返回它的初始狀態。 * 這個方法不接收任何參數 **Code examples:** 調用destroy 方法： ``` $( ".selector" ).slider( "destroy" ); ``` ### disable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 禁用滑塊組件。 * 這個方法不接收任何參數 **Code examples:** 調用disable 方法： ``` $( ".selector" ).slider( "disable" ); ``` ### enable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 啟用滑塊組件。 * 這個方法不接收任何參數 **Code examples:** 調用enable 方法： ``` $( ".selector" ).slider( "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" ).slider( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個包含有描述當前滑塊組件選項哈希值的鍵/值對。 * 這個方法不接收任何參數 **Code examples:** 調用這個方法： ``` var options = $( ".selector" ).slider( "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`參數指定的選項的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置的選項的名稱。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要為選項設置的參數值。 **Code examples:** 調用這個方法： ``` $( ".selector" ).slider( "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/)) 設置一個或多個滑塊組件的選項值。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的選項名與值之間的映射關系。 **Code examples:** 調用這個方法： ``` $( ".selector" ).slider( "option", { disabled: true } ); ``` ### value()Returns: [Number](http://api.jquery.com/Types/#Number) 獲取滑塊組件的值。 * 這個方法不接收任何參數 **Code examples:** 調用這個方法： ``` var selection = $( ".selector" ).slider( "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)用來設置的值 **Code examples:** 調用這個方法： ``` $( ".selector" ).slider( "value", 55 ); ``` ### values()Returns: [Array](http://api.jquery.com/Types/#Array) 獲取所有手柄的值.（愚人碼頭注：適用于多手柄的滑塊） * 這個方法不接收任何參數 **Code examples:** 調用這個方法： ``` var values = $( ".selector" ).slider( "values" ); ``` ### values( index )Returns: [Number](http://api.jquery.com/Types/#Number) 獲取指定手柄的值。（愚人碼頭注：適用于多手柄的滑塊） * **index**Type: [Integer](http://api.jquery.com/Types/#Integer)從0開始計數的手柄索引值。 **Code examples:** 調用這個方法： ``` var value = $( ".selector" ).slider( "values", 0 ); ``` ### values( index, value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 設置指定手柄的值。（愚人碼頭注：適用于多手柄的滑塊） * **index**Type: [Integer](http://api.jquery.com/Types/#Integer)從0開始計數的手柄索引值。 * **value**Type: [Number](http://api.jquery.com/Types/#Number)要設置的值 **Code examples:** 調用這個方法： ``` $( ".selector" ).slider( "values", 0, 55 ); ``` ### values( values )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 設置所有手柄的值。（愚人碼頭注：適用于多手柄的滑塊） * **values**Type: [Array](http://api.jquery.com/Types/#Array)要設置的值。 **Code examples:** 調用這個方法： ``` $( ".selector" ).slider( "values", [ 55, 105 ] ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個滑塊元素的`jQuery`對象。 * 這個方法不接收任何參數 **Code examples:** 調用widget 方法： ``` var widget = $( ".selector" ).slider( "widget" ); ``` ## Events ### change( event, ui )Type: `slidechange` 當用戶滑動一個手柄后，如果滑塊的值改變了，就會觸發這個事件；或者通過[`value`](#method-value)方法改變手柄值。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **handle**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象，表示被改變的手柄 * **value**Type: [Number](http://api.jquery.com/Types/#Number)當前滑塊的值。 **Code examples:** 使用change 回調函數指定事件: ``` $( ".selector" ).slider({ change: function( event, ui ) {} }); ``` 綁定事件偵聽器到slidechange事件： ``` $( ".selector" ).on( "slidechange", function( event, ui ) {} ); ``` ### create( event, ui )Type: `slidecreate` 當滑塊組件被創建時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意: `ui`對象是空的，但是為了與其它元素保持一直，它總是被包含。_ **Code examples:** 使用create 回調函數指定事件: ``` $( ".selector" ).slider({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 slidecreate 事件: ``` $( ".selector" ).on( "slidecreate", function( event, ui ) {} ); ``` ### slide( event, ui )Type: `slide` 這個事件鼠標滑動滑塊時觸發。`ui.value`作為提供給事件的價值，表示將作為該當前移動手柄的結果值。取消該事件會阻止手柄移動和手柄將繼續其先前的值。取消該事件會阻止手柄移動并且手柄將繼續其先前的值。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **handle**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象，表示當前移動的手柄 * **value**Type: [Number](http://api.jquery.com/Types/#Number)如果事件沒有被取消，該手柄將移動到值。 * **values**Type: [Array](http://api.jquery.com/Types/#Array)一個多手柄滑塊當前值的數組。 **Code examples:** 使用slide 回調函數指定事件: ``` $( ".selector" ).slider({ slide: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 slide 事件: ``` $( ".selector" ).on( "slide", function( event, ui ) {} ); ``` ### start( event, ui )Type: `slidestart` 當用戶開始滑動滑塊時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **handle**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象，表示當前移動的手柄 * **value**Type: [Number](http://api.jquery.com/Types/#Number)滑塊的當前值 **Code examples:** 使用start 回調函數指定事件: ``` $( ".selector" ).slider({ start: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 slidestart 事件: ``` $( ".selector" ).on( "slidestart", function( event, ui ) {} ); ``` ### stop( event, ui )Type: `slidestop` 當用戶滑動滑塊后觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **handle**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象，表示移動后手柄。 * **value**Type: [Number](http://api.jquery.com/Types/#Number)滑塊的當前值 **Code examples:** 使用stop 回調函數指定事件: ``` $( ".selector" ).slider({ stop: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 slidestop 事件: ``` $( ".selector" ).on( "slidestop", function( event, ui ) {} ); ``` ## Example: #### 一個簡單的 jQuery UI 滑塊（Slider）。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>slider demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css"> <style>#slider { margin: 10px; } </style> <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> <div id="slider"></div> <script> $( "#slider" ).slider(); </script> </body> </html> ```