Selectable Widget · jQuery UI API 中文文檔 1.10

# Selectable Widget Categories: [Interactions](http://www.css88.com/jquery-ui-api/category/interactions/ "View all posts in Interactions") ## version added: 1.0 **Description:** 使用鼠標選擇一個或一組元素。 ## QuickNav[Examples](#entry-examples) ### Options + [appendTo](#option-appendTo) + [autoRefresh](#option-autoRefresh) + [cancel](#option-cancel) + [delay](#option-delay) + [disabled](#option-disabled) + [distance](#option-distance) + [filter](#option-filter) + [tolerance](#option-tolerance) ### Methods + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [option](#method-option) + [refresh](#method-refresh) + [widget](#method-widget) ### Events + [create](#event-create) + [selected](#event-selected) + [selecting](#event-selecting) + [start](#event-start) + [stop](#event-stop) + [unselected](#event-unselected) + [unselecting](#event-unselecting)jQuery UI Selectable 插件允許一個元素被鼠標劃出的選擇區域選中. 同樣, 元素也可以被點擊選中或者同時按住 Ctrl/Meta鍵, 允許多個(非連續)的選擇. ### 依賴關系 * [UI Core](/category/ui-core/) * [Widget Factory](/jQuery.widget/) * [Mouse Interaction](/mouse/) ### 其他注意事項： * 這個widget需要一些功能性的CSS，否則將無法正常工作。如果你建立一個自定義的主題，使用widget指定的CSS文件作為一個激活點。 ## Options ### appendTo**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `"body"`選擇幫手（套索）應追加到哪個元素。**Code examples:** 使用指定的 `appendTo` 參數初始化selectable : ``` $( ".selector" ).selectable({ appendTo: "#someElem" }); ``` 在初始化后設置或者獲取 `appendTo` 選項 : ``` // getter var appendTo = $( ".selector" ).selectable( "option", "appendTo" ); // setter $( ".selector" ).selectable( "option", "appendTo", "#someElem" ); ``` ### autoRefresh**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `true`這個選項確定每個選擇操作開始時如何刷新(重新計算)每個選擇項的位置和大小. 如果你有很多很多選擇項, 你應當設置此項為false并且手動調用[`refresh()`](#method-refresh) 方法.**Code examples:** 使用指定的 `autoRefresh` 參數初始化selectable : ``` $( ".selector" ).selectable({ autoRefresh: false }); ``` 在初始化后設置或者獲取 `autoRefresh` 選項 : ``` // getter var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" ); // setter $( ".selector" ).selectable( "option", "autoRefresh", false ); ``` ### cancel**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `"input,textarea,button,select,option"`如果你使用了匹配選擇器,符合匹配的元素將被禁止可選.**Code examples:** 使用指定的 `cancel` 參數初始化selectable : ``` $( ".selector" ).selectable({ cancel: "a,.cancel" }); ``` 在初始化后設置或者獲取 `cancel` 選項 : ``` // getter var cancel = $( ".selector" ).selectable( "option", "cancel" ); // setter $( ".selector" ).selectable( "option", "cancel", "a,.cancel" ); ``` ### delay**Type:** [Integer](http://api.jquery.com/Types/#Integer) **Default:** `0`定義需要經過多少毫秒后選擇才會開始. 這可以預防意外的點擊造成元素被選擇.**Code examples:** 使用指定的 `delay` 參數初始化selectable : ``` $( ".selector" ).selectable({ delay: 150 }); ``` 在初始化后設置或者獲取 `delay` 選項 : ``` // getter var delay = $( ".selector" ).selectable( "option", "delay" ); // setter $( ".selector" ).selectable( "option", "delay", 150 ); ``` ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為 `true` 將禁止selectable。**Code examples:** 使用指定的 `disabled` 參數初始化selectable : ``` $( ".selector" ).selectable({ disabled: true }); ``` 在初始化后設置或者獲取 `disabled` 選項 : ``` // getter var disabled = $( ".selector" ).selectable( "option", "disabled" ); // setter $( ".selector" ).selectable( "option", "disabled", true ); ``` ### distance**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `0`定義需要移動多少個像素選擇才會開始. 如果指定了該項, 選擇不會馬上開始,而是會在鼠標移動了指定像素的距離之后才會開始.**Code examples:** 使用指定的 `distance` 參數初始化selectable : ``` $( ".selector" ).selectable({ distance: 30 }); ``` 在初始化后設置或者獲取 `distance` 選項 : ``` // getter var distance = $( ".selector" ).selectable( "option", "distance" ); // setter $( ".selector" ).selectable( "option", "distance", 30 ); ``` ### filter**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `"*"`匹配子元素中那些符合條件的元素才可以被選擇.**Code examples:** 使用指定的 `filter` 參數初始化selectable : ``` $( ".selector" ).selectable({ filter: "li" }); ``` 在初始化后設置或者獲取 `filter` 選項 : ``` // getter var filter = $( ".selector" ).selectable( "option", "filter" ); // setter $( ".selector" ).selectable( "option", "filter", "li" ); ``` ### tolerance**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `"touch"`指定那種模式，用來測試套索是否應該選擇一個項目。允許使用的值: * `"fit"`: 套索完全重疊的項目。 * `"touch"`: 套索重疊的項目任何部分。 **Code examples:** 使用指定的 `tolerance` 參數初始化selectable : ``` $( ".selector" ).selectable({ tolerance: "fit" }); ``` 在初始化后設置或者獲取 `tolerance` 選項 : ``` // getter var tolerance = $( ".selector" ).selectable( "option", "tolerance" ); // setter $( ".selector" ).selectable( "option", "tolerance", "fit" ); ``` ## Methods ### destroy() 完全移除selectable功能. 這將使元素返回到之前的初始化狀態. * 這個方法不接受任何參數。 **Code examples:** 調用 destroy 方法: ``` $( ".selector" ).selectable( "destroy" ); ``` ### disable() 禁用selectable. * 這個方法不接受任何參數。 **Code examples:** 調用 disable 方法: ``` $( ".selector" ).selectable( "disable" ); ``` ### enable() 啟用 selectable. * 這個方法不接受任何參數。 **Code examples:** 調用 enable 方法: ``` $( ".selector" ).selectable( "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" ).selectable( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個對象，它包含表示當前resizable的選項hash的鍵/值對。 * 這個方法不接受任何參數。 **Code examples:** 調用這個方法: ``` var options = $( ".selector" ).selectable( "option" ); ``` ### option( optionName, value ) 通過指定的`optionName`，設置selectable的相關選項值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置值的選項名。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要設置選項的值。 **Code examples:** 調用這個方法: ``` $( ".selector" ).selectable( "option", "disabled", true ); ``` ### option( options ) 為selectable設置一個或多個選項。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)用來設置的選項/值對的對象。 **Code examples:** 調用這個方法: ``` $( ".selector" ).selectable( "option", { disabled: true } ); ``` ### refresh() 刷新每個選擇項的位置和大小. 這個方法用來手動重新計算選擇項的位置和大小,在[`autoRefresh`](#option-autoRefresh)設置為`false`時很有用。 * 這個方法不接受任何參數。 **Code examples:** 調用 refresh 方法: ``` $( ".selector" ).selectable( "refresh" ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個`jQuery`，它包含了selectable元素。 * 這個方法不接受任何參數。 **Code examples:** 調用 widget 方法: ``` var widget = $( ".selector" ).selectable( "widget" ); ``` ## Events ### create( event, ui )Type: `selectablecreate` 此事件會在 selectable 創建時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui` 對象是空對象，包括是為了和其他事件的一致性。_ **Code examples:** 使用指定的 create 回調初始化一個selectable： ``` $( ".selector" ).selectable({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽到 selectablecreate 事件： ``` $( ".selector" ).on( "selectablecreate", function( event, ui ) {} ); ``` ### selected( event, ui )Type: `selectableselected` 此事件會在選擇操作結束時，在添加到選擇的每個元素上觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **selected**Type: [Element](http://api.jquery.com/Types/#Element)已被選擇的selectable項。 **Code examples:** 使用指定的 selected 回調初始化一個selectable： ``` $( ".selector" ).selectable({ selected: function( event, ui ) {} }); ``` 綁定一個事件監聽到selectableselected事件： ``` $( ".selector" ).on( "selectableselected", function( event, ui ) {} ); ``` ### selecting( event, ui )Type: `selectableselecting` 此事件會在選擇操作過程中，在添加到選擇的每個元素上觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **selecting**Type: [Element](http://api.jquery.com/Types/#Element)當前已被選擇的selectable項。 **Code examples:** 使用指定的 selecting 回調初始化一個selectablec： ``` $( ".selector" ).selectable({ selecting: function( event, ui ) {} }); ``` 綁定一個事件監聽到 selectableselecting 事件： ``` $( ".selector" ).on( "selectableselecting", function( event, ui ) {} ); ``` ### start( event, ui )Type: `selectablestart` 這個事件將在選擇操作開始時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui` 對象是空對象，包括是為了和其他事件的一致性。_ **Code examples:** 使用指定的 start 回調初始化一個selectable： ``` $( ".selector" ).selectable({ start: function( event, ui ) {} }); ``` 綁定一個事件監聽到 selectablestart 事件： ``` $( ".selector" ).on( "selectablestart", function( event, ui ) {} ); ``` ### stop( event, ui )Type: `selectablestop` 這個事件將在選擇操作結束后觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui` 對象是空對象，包括是為了和其他事件的一致性。_ **Code examples:** 使用指定的 stop 回調初始化一個selectable： ``` $( ".selector" ).selectable({ stop: function( event, ui ) {} }); ``` 綁定一個事件監聽到 selectablestop 事件： ``` $( ".selector" ).on( "selectablestop", function( event, ui ) {} ); ``` ### unselected( event, ui )Type: `selectableunselected` 此事件會在選擇操作結束時，在從選擇元素集合中移除的每個元素上觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **unselected**Type: [Element](http://api.jquery.com/Types/#Element)已被取消選中的可選擇項。 **Code examples:** 使用指定的 unselected 回調初始化一個selectable： ``` $( ".selector" ).selectable({ unselected: function( event, ui ) {} }); ``` 綁定一個事件監聽到 selectableunselected 事件： ``` $( ".selector" ).on( "selectableunselected", function( event, ui ) {} ); ``` ### unselecting( event, ui )Type: `selectableunselecting` 此事件會在選擇操作過程中，在從選擇元素集合中移除的每個元素上觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **unselecting**Type: [Element](http://api.jquery.com/Types/#Element)當前已被取消選中的可選擇項。 **Code examples:** 使用指定的 unselecting 回調初始化一個selectable： ``` $( ".selector" ).selectable({ unselecting: function( event, ui ) {} }); ``` 綁定一個事件監聽到 selectableunselecting 事件： ``` $( ".selector" ).on( "selectableunselecting", function( event, ui ) {} ); ``` ## Example: #### A simple jQuery UI Selectable. ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>selectable demo</title> <link rel="stylesheet" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css"> <style> #selectable .ui-selecting { background: #ccc; } #selectable .ui-selected { background: #999; } </style> <script src="http://code.jquery.com/jquery-1.9.1.js"></script> <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.js"></script> </head> <body> <ul id="selectable"> <li>Item 1</li> <li>Item 2</li> <li>Item 3</li> <li>Item 4</li> <li>Item 5</li> </ul> <script> $( "#selectable" ).selectable(); </script> </body> </html> ```