jQuery UI API - 可選擇小部件（Selectable Widget） · W3School jQuery UI 教程

# jQuery UI API - 可選擇小部件（Selectable Widget） ## 所屬類別 [交互（Interactions）](ref-interactions.html) ## 用法 **描述：**使用鼠標選擇單個元素或一組元素。 **版本新增：**1.0 **依賴：** * [UI 核心（UI Core）](ref-ui-core.html) * [部件庫（Widget Factory）](api-jQuery-widget.html) * [鼠標交互（Mouse Interaction）](api-mouse.html) **注釋：**jQuery UI 可選擇（Selectable）插件允許通過鼠標拖拽選擇元素（有時被稱為一個套索）。可以在按住 ctrl/meta 鍵的同時單擊或拖動來選擇多個（不連續的）元素。 **附加說明：**該部件要求一些功能性的 CSS，否則將無法工作。如果您創建了一個自定義的主題，請使用小部件指定的 CSS 文件作為起點。 ### 快速導航 | 選項 | 方法 | 事件 | | --- | --- | --- | | [appendTo](#option-appendTo)[autoRefresh](#option-autoRefresh)[cancel](#option-cancel)[delay](#option-delay)[disabled](#option-disabled)[distance](#option-distance)[filter](#option-filter)[tolerance](#option-tolerance) | [destroy](#method-destroy)[disable](#method-disable)[enable](#method-enable)[option](#method-option)[refresh](#method-refresh)[widget](#method-widget) | [create](#event-create)[selected](#event-selected)[selecting](#event-selecting)[start](#event-start)[stop](#event-stop)[unselected](#event-unselected)[unselecting](#event-unselecting) | #### appendTo **類型**：Selector **描述**：選擇助手（套索）要被添加到哪一個元素。 **代碼實例：** 初始化帶有指定 `appendTo` 選項的 draggable： ``` $( ".selector" ).selectable({ appendTo: "#someElem" }); ``` 在初始化后，獲取或設置 `appendTo` 選項： ``` // getter var appendTo = $( ".selector" ).selectable( "option", "appendTo" ); // setter $( ".selector" ).selectable( "option", "appendTo", "#someElem" ); ``` **默認值**："body" #### autoRefresh **類型**：Boolean **描述**：該選項決定是否在每個選擇操作的開始時更新（重新計算）每個選擇項的位置和尺寸。如果您有多個項目，您可能要設置該選項為 false，并手動調用 `[refresh()](#method-refresh)` 方法。 **代碼實例：** 初始化帶有指定 `autoRefresh` 選項的 draggable： ``` $( ".selector" ).selectable({ autoRefresh: false }); ``` 在初始化后，獲取或設置 `autoRefresh` 選項： ``` // getter var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" ); // setter $( ".selector" ).selectable( "option", "autoRefresh", false ); ``` **默認值**：true #### cancel **類型**：Selector **描述**：防止從匹配選擇器的元素上開始選擇。 **代碼實例：** 初始化帶有指定 `cancel` 選項的 selectable： ``` $( ".selector" ).selectable({ cancel: "a,.cancel" }); ``` 在初始化后，獲取或設置 `cancel` 選項： ``` // getter var cancel = $( ".selector" ).selectable( "option", "cancel" ); // setter $( ".selector" ).selectable( "option", "cancel", "a,.cancel" ); ``` **默認值**："input, textarea, button, select, option" #### delay **類型**：Number **描述**：鼠標按下后直到選擇開始的時間，以毫秒計。該選項可以防止點擊在某個元素上時不必要的選擇。 **代碼實例：** 初始化帶有指定 `delay` 選項的 selectable： ``` $( ".selector" ).selectable({ delay: 150 }); ``` 在初始化后，獲取或設置 `delay` 選項： ``` // getter var delay = $( ".selector" ).selectable( "option", "delay" ); // setter $( ".selector" ).selectable( "option", "delay", 150 ); ``` **默認值**：0 #### disabled **類型**：Boolean **描述**：如果設置為 `true`，則禁用該 selectable。 **代碼實例：** 初始化帶有指定 `disabled` 選項的 selectable： ``` $( ".selector" ).selectable({ disabled: true }); ``` 在初始化后，獲取或設置 `disabled` 選項： ``` // getter var disabled = $( ".selector" ).selectable( "option", "disabled" ); // setter $( ".selector" ).selectable( "option", "disabled", true ); ``` **默認值**：false #### distance **類型**：Number **描述**：鼠標按下后選擇開始前必須移動的距離，以像素計。如果指定了該選項，選擇只有在鼠標拖拽超出指定距離時才會開始。該選項可以防止點擊在某個元素上時不必要的選擇。 **代碼實例：** 初始化帶有指定 `distance` 選項的 selectable： ``` $( ".selector" ).selectable({ distance: 30 }); ``` 在初始化后，獲取或設置 `distance` 選項： ``` // getter var distance = $( ".selector" ).selectable( "option", "distance" ); // setter $( ".selector" ).selectable( "option", "distance", 30 ); ``` **默認值**：0 #### filter **類型**：Selector **描述**：要制作選擇項（可被選擇的）的匹配的子元素。 **代碼實例：** 初始化帶有指定 `filter` 選項的 selectable： ``` $( ".selector" ).selectable({ filter: "li" }); ``` 在初始化后，獲取或設置 `filter` 選項： ``` // getter var filter = $( ".selector" ).selectable( "option", "filter" ); // setter $( ".selector" ).selectable( "option", "filter", "li" ); ``` **默認值**："*" #### tolerance **類型**：String **描述**：指定用于測試套索是否選擇一個項目的模式。可能的值： * `"fit"`：套索完全重疊在項目上。 * `"touch"`：套索重疊在項目上，任何比例皆可。 **代碼實例：** 初始化帶有指定 `tolerance` 選項的 selectable： ``` $( ".selector" ).selectable({ tolerance: "fit" }); ``` 在初始化后，獲取或設置 `tolerance` 選項： ``` // getter var tolerance = $( ".selector" ).selectable( "option", "tolerance" ); // setter $( ".selector" ).selectable( "option", "tolerance", "fit" ); ``` **默認值**："touch" #### 方法 #### destroy() **類型**：jQuery (plugin only) **描述**：完全移除 selectable 功能。這會把元素返回到它的預初始化狀態。 * 該方法不接受任何參數。 **代碼實例：** 調用 destroy 方法： ``` $( ".selector" ).selectable( "destroy" ); ``` #### disable() **類型**：jQuery (plugin only) **描述**：禁用 selectable。 * 該方法不接受任何參數。 **代碼實例：** 調用 disable 方法： ``` $( ".selector" ).selectable( "disable" ); ``` #### enable() **類型**：jQuery (plugin only) **描述**：啟用 selectable。 * 該方法不接受任何參數。 **代碼實例：** 調用 enable 方法： ``` $( ".selector" ).selectable( "enable" ); ``` #### option( optionName ) **類型**：Object **描述**：獲取當前與指定的 `optionName` 關聯的值。 * **optionName** 類型：String 描述：要獲取的選項的名稱。 **代碼實例：** 調用該方法： ``` var isDisabled = $( ".selector" ).selectable( "option", "disabled" ); ``` #### option() **類型**：PlainObject **描述**：獲取一個包含鍵/值對的對象，鍵/值對表示當前 selectable 選項哈希。 * 該方法不接受任何參數。 **代碼實例：** 調用該方法： ``` var options = $( ".selector" ).selectable( "option" ); ``` #### option( optionName, value ) **類型**：jQuery (plugin only) **描述**：設置與指定的 `optionName` 關聯的 selectable 選項的值。 * **optionName** 類型：String 描述：要設置的選項的名稱。 * **value** 類型：Object 描述：要為選項設置的值。 **代碼實例：** 調用該方法： ``` $( ".selector" ).selectable( "option", "disabled", true ); ``` #### option( options ) **類型**：jQuery (plugin only) **描述**：為 selectable 設置一個或多個選項。 * **options** 類型：Object 描述：要設置的 option-value 對。 **代碼實例：** 調用該方法： ``` $( ".selector" ).selectable( "option", { disabled: true } ); ``` #### refresh() **類型**：jQuery (plugin only) **描述**：更新每個選擇項元素的位置和尺寸。當 `[autoRefresh](#option-autoRefresh)` 選項被設置為 false 時，該方法可用于手動重新計算每個選擇項的位置和尺寸。 * 該方法不接受任何參數。 **代碼實例：** 調用 refresh 方法： ``` $( ".selector" ).selectable( "refresh" ); ``` #### widget() **類型**：jQuery **描述**：返回一個包含 selectable 元素的 `jQuery` 對象。 * 該方法不接受任何參數。 **代碼實例：** 調用 widget 方法： ``` var widget = $( ".selector" ).selectable( "widget" ); ``` #### 事件 #### create( event, ui ) **類型**：selectablecreate **描述**：當 selectable 被創建時觸發。 * **event** 類型：Event * **ui** 類型：Object 注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。 **代碼實例：** 初始化帶有指定 create 回調的 selectable： ``` $( ".selector" ).selectable({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectablecreate 事件： ``` $( ".selector" ).on( "selectablecreate", function( event, ui ) {} ); ``` #### selected( event, ui ) **類型**：selectableselected **描述**：當每個元素被添加選擇時，在選擇操作結尾觸發。 * **event** 類型：Event * **ui** 類型：Object * **selected** 類型：Element 描述：被選擇的可選擇項目。 **代碼實例：** 初始化帶有指定 selected 回調的 selectable： ``` $( ".selector" ).selectable({ selected: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectableselected 事件： ``` $( ".selector" ).on( "selectableselected", function( event, ui ) {} ); ``` #### selecting( event, ui ) **類型**：selectableselecting **描述**：當每個元素被添加選擇時，在選擇操作期間觸發。 * **event** 類型：Event * **ui** 類型：Object * **selecting** 類型：Element 描述：正被選擇的當前可選擇項目。 **代碼實例：** 初始化帶有指定 selecting 回調的 selectable： ``` $( ".selector" ).selectable({ selecting: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectableselecting 事件： ``` $( ".selector" ).on( "selectableselecting", function( event, ui ) {} ); ``` #### start( event, ui ) **類型**：selectablestart **描述**：在選擇操作開頭觸發。 * **event** 類型：Event * **ui** 類型：Object 注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。 **代碼實例：** 初始化帶有指定 start 回調的 selectable： ``` $( ".selector" ).selectable({ start: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectablestart 事件： ``` $( ".selector" ).on( "selectablestart", function( event, ui ) {} ); ``` #### stop( event, ui ) **類型**：selectablestop **描述**：在選擇操作結尾觸發。 * **event** 類型：Event * **ui** 類型：Object 注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。 **代碼實例：** 初始化帶有指定 stop 回調的 selectable： ``` $( ".selector" ).selectable({ stop: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectablestop 事件： ``` $( ".selector" ).on( "selectablestop", function( event, ui ) {} ); ``` #### unselected( event, ui ) **類型**：selectableunselected **描述**：當每個元素從選擇中被移除時，在選擇操作結尾觸發。 * **event** 類型：Event * **ui** 類型：Object * **unselected** 類型：Element 描述：未被選擇的可選擇項目。 **代碼實例：** 初始化帶有指定 unselected 回調的 selectable： ``` $( ".selector" ).selectable({ unselected: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectableunselected 事件： ``` $( ".selector" ).on( "selectableunselected", function( event, ui ) {} ); ``` #### unselecting( event, ui ) **類型**：selectableunselecting **描述**：當每個元素從選擇中被移除時，在選擇操作期間觸發。 * **event** 類型：Event * **ui** 類型：Object * **unselecting** 類型：Element 描述：正未被選擇的當前可選擇項目。 **代碼實例：** 初始化帶有指定 unselecting 回調的 selectable： ``` $( ".selector" ).selectable({ unselecting: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 selectableunselecting 事件： ``` $( ".selector" ).on( "selectableunselecting", function( event, ui ) {} ); ``` ## 實例一個簡單的 jQuery UI 可選擇小部件（Selectable Widget）。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>可選擇小部件（Selectable Widget）演示</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css"> <style> #selectable .ui-selecting { background: #ccc; } #selectable .ui-selected { background: #999; } </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> <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> ```