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

所屬類別

交互（Interactions）

用法

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

版本新增：1.0

依賴：

注釋：jQuery UI 可選擇（Selectable）插件允許通過鼠標拖拽選擇元素（有時被稱為一個套索）?？梢栽诎醋?ctrl/meta 鍵的同時單擊或拖動來選擇多個（不連續(xù)的）元素。

附加說明：該部件要求一些功能性的 CSS，否則將無法工作。如果您創(chuàng)建了一個自定義的主題，請使用小部件指定的 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 功能。這會把元素返回到它的預初始化狀態(tài)。
  • 該方法不接受任何參數(shù)。

代碼實例：

調用 destroy 方法：

$( ".selector" ).selectable( "destroy" );
disable() jQuery (plugin only) 禁用 selectable。
  • 該方法不接受任何參數(shù)。

代碼實例：

調用 disable 方法：

$( ".selector" ).selectable( "disable" );
enable() jQuery (plugin only) 啟用 selectable。
  • 該方法不接受任何參數(shù)。

代碼實例：

調用 enable 方法：

$( ".selector" ).selectable( "enable" );
option( optionName ) Object 獲取當前與指定的 optionName 關聯(lián)的值。
  • optionName
    類型：String
    描述：要獲取的選項的名稱。

代碼實例：

調用該方法：

var isDisabled = $( ".selector" ).selectable( "option", "disabled" );
option() PlainObject 獲取一個包含鍵/值對的對象，鍵/值對表示當前 selectable 選項哈希。
  • 該方法不接受任何參數(shù)。

代碼實例：

調用該方法：

var options = $( ".selector" ).selectable( "option" );
option( optionName, value ) jQuery (plugin only) 設置與指定的 optionName 關聯(lián)的 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 時，該方法可用于手動重新計算每個選擇項的位置和尺寸。
  • 該方法不接受任何參數(shù)。

代碼實例：

調用 refresh 方法：

$( ".selector" ).selectable( "refresh" );
widget() jQuery 返回一個包含 selectable 元素的 jQuery 對象。
  • 該方法不接受任何參數(shù)。

代碼實例：

調用 widget 方法：

var widget = $( ".selector" ).selectable( "widget" );

事件 類型 描述
create( event, ui ) selectablecreate 當 selectable 被創(chuàng)建時觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object

注意：ui 對象是空的，這里包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 create 回調的 selectable：

$( ".selector" ).selectable({
  create: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 selectablecreate 事件：

$( ".selector" ).on( "selectablecreate", function( event, ui ) {} );
selected( event, ui ) selectableselected 當每個元素被添加選擇時，在選擇操作結尾觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object
    • selected
      類型：Element
      描述：被選擇的可選擇項目。

代碼實例：

初始化帶有指定 selected 回調的 selectable：

$( ".selector" ).selectable({
  selected: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 selectableselected 事件：

$( ".selector" ).on( "selectableselected", function( event, ui ) {} );
selecting( event, ui ) selectableselecting 當每個元素被添加選擇時，在選擇操作期間觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object
    • selecting
      類型：Element
      描述：正被選擇的當前可選擇項目。

代碼實例：

初始化帶有指定 selecting 回調的 selectable：

$( ".selector" ).selectable({
  selecting: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 selectableselecting 事件：

$( ".selector" ).on( "selectableselecting", function( event, ui ) {} );
start( event, ui ) selectablestart 在選擇操作開頭觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object

注意：ui 對象是空的，這里包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 start 回調的 selectable：

$( ".selector" ).selectable({
  start: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 selectablestart 事件：

$( ".selector" ).on( "selectablestart", function( event, ui ) {} );
stop( event, ui ) selectablestop 在選擇操作結尾觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object

注意：ui 對象是空的，這里包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 stop 回調的 selectable：

$( ".selector" ).selectable({
  stop: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 selectablestop 事件：

$( ".selector" ).on( "selectablestop", function( event, ui ) {} );
unselected( event, ui ) selectableunselected 當每個元素從選擇中被移除時，在選擇操作結尾觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object
    • unselected
      類型：Element
      描述：未被選擇的可選擇項目。

代碼實例：

初始化帶有指定 unselected 回調的 selectable：

$( ".selector" ).selectable({
  unselected: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 selectableunselected 事件：

$( ".selector" ).on( "selectableunselected", function( event, ui ) {} );
unselecting( event, ui ) selectableunselecting 當每個元素從選擇中被移除時，在選擇操作期間觸發(fā)。
  • event
    類型：Event
  • ui
    類型：Object
    • unselecting
      類型：Element
      描述：正未被選擇的當前可選擇項目。

代碼實例：

初始化帶有指定 unselecting 回調的 selectable：

$( ".selector" ).selectable({
  unselecting: function( event, ui ) {}
});

綁定一個事件監(jiān)聽器到 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"  rel="external nofollow" target="_blank" >
  <style>
  #selectable .ui-selecting {
    background: #ccc;
  }
  #selectable .ui-selected {
    background: #999;
  }
  </style>
  <script src="http://code.jquery.com/jquery-1.10.2.js" rel="external nofollow" ></script>
  <script src="http://code.jquery.com/ui/1.10.4/jquery-ui.js" rel="external nofollow" ></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>

查看演示