jQuery UI API - 可選擇小部件（Selectable Widget）

所屬類別

交互（Interactions）

用法

描述：使用滑鼠選擇單個元素或一組元素。

版本新增：1.0

依賴：

注釋：jQuery UI 可選擇（Selectable）插件允許通過滑鼠拖拽選擇元素（有時被稱為一個套索）。可以在按住 ctrl/meta 鍵的同時單擊或拖動來選擇多個（不連續的）元素。

附加說明：該部件要求一些功能性的 CSS，否則將無法工作。如果您創建了一個自定義的主題，請使用小部件指定的 CSS 檔作為起點。

快速導航

選項 方法 事件

選項 類型 描述 默認值
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() 方法。

代碼實例：

初始化帶有指定 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 選項被設置為 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>