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

所屬類別

交互（Interactions）

用法

描述：使用鼠標(biāo)選擇單個(gè)元素或一組元素。

版本新增：1.0

依賴：

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

附加說明：該部件要求一些功能性的 CSS，否則將無法工作。如果您創(chuàng)建了一個(gè)自定義的主題，請(qǐng)使用小部件指定的 CSS 文件作為起點(diǎn)。

快速導(dǎo)航

選項(xiàng) 方法 事件

選項(xiàng) 類型 描述 默認(rèn)值
appendTo Selector 選擇助手（套索）要被添加到哪一個(gè)元素。

代碼實(shí)例：

初始化帶有指定 appendTo 選項(xiàng)的 draggable：

$( ".selector" ).selectable({ appendTo: "#someElem" });

在初始化后，獲取或設(shè)置 appendTo 選項(xiàng)：

// getter
var appendTo = $( ".selector" ).selectable( "option", "appendTo" );
 
// setter
$( ".selector" ).selectable( "option", "appendTo", "#someElem" );
"body"
autoRefresh Boolean 該選項(xiàng)決定是否在每個(gè)選擇操作的開始時(shí)更新（重新計(jì)算）每個(gè)選擇項(xiàng)的位置和尺寸。如果您有多個(gè)項(xiàng)目，您可能要設(shè)置該選項(xiàng)為 false，并手動(dòng)調(diào)用 refresh() 方法。

代碼實(shí)例：

初始化帶有指定 autoRefresh 選項(xiàng)的 draggable：

$( ".selector" ).selectable({ autoRefresh: false });

在初始化后，獲取或設(shè)置 autoRefresh 選項(xiàng)：

// getter
var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );
 
// setter
$( ".selector" ).selectable( "option", "autoRefresh", false );
true
cancel Selector 防止從匹配選擇器的元素上開始選擇。

代碼實(shí)例：

初始化帶有指定 cancel 選項(xiàng)的 selectable：

$( ".selector" ).selectable({ cancel: "a,.cancel" });

在初始化后，獲取或設(shè)置 cancel 選項(xiàng)：

// getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );
 
// setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );
"input, textarea, button, select, option"
delay Number 鼠標(biāo)按下后直到選擇開始的時(shí)間，以毫秒計(jì)。該選項(xiàng)可以防止點(diǎn)擊在某個(gè)元素上時(shí)不必要的選擇。

代碼實(shí)例：

初始化帶有指定 delay 選項(xiàng)的 selectable：

$( ".selector" ).selectable({ delay: 150 });

在初始化后，獲取或設(shè)置 delay 選項(xiàng)：

// getter
var delay = $( ".selector" ).selectable( "option", "delay" );
 
// setter
$( ".selector" ).selectable( "option", "delay", 150 );
0
disabled Boolean 如果設(shè)置為 true，則禁用該 selectable。

代碼實(shí)例：

初始化帶有指定 disabled 選項(xiàng)的 selectable：

$( ".selector" ).selectable({ disabled: true });

在初始化后，獲取或設(shè)置 disabled 選項(xiàng)：

// getter
var disabled = $( ".selector" ).selectable( "option", "disabled" );
 
// setter
$( ".selector" ).selectable( "option", "disabled", true );
false
distance Number 鼠標(biāo)按下后選擇開始前必須移動(dòng)的距離，以像素計(jì)。如果指定了該選項(xiàng)，選擇只有在鼠標(biāo)拖拽超出指定距離時(shí)才會(huì)開始。該選項(xiàng)可以防止點(diǎn)擊在某個(gè)元素上時(shí)不必要的選擇。

代碼實(shí)例：

初始化帶有指定 distance 選項(xiàng)的 selectable：

$( ".selector" ).selectable({ distance: 30 });

在初始化后，獲取或設(shè)置 distance 選項(xiàng)：

// getter
var distance = $( ".selector" ).selectable( "option", "distance" );
 
// setter
$( ".selector" ).selectable( "option", "distance", 30 );
0
filter Selector 要制作選擇項(xiàng)（可被選擇的）的匹配的子元素。

代碼實(shí)例：

初始化帶有指定 filter 選項(xiàng)的 selectable：

$( ".selector" ).selectable({ filter: "li" });

在初始化后，獲取或設(shè)置 filter 選項(xiàng)：

// getter
var filter = $( ".selector" ).selectable( "option", "filter" );
 
// setter
$( ".selector" ).selectable( "option", "filter", "li" );
"*"
tolerance String 指定用于測試套索是否選擇一個(gè)項(xiàng)目的模式。可能的值：
  • "fit"：套索完全重疊在項(xiàng)目上。
  • "touch"：套索重疊在項(xiàng)目上，任何比例皆可。

代碼實(shí)例：

初始化帶有指定 tolerance 選項(xiàng)的 selectable：

$( ".selector" ).selectable({ tolerance: "fit" });

在初始化后，獲取或設(shè)置 tolerance 選項(xiàng)：

// getter
var tolerance = $( ".selector" ).selectable( "option", "tolerance" );
 
// setter
$( ".selector" ).selectable( "option", "tolerance", "fit" );
"touch"

方法 返回 描述
destroy() jQuery (plugin only) 完全移除 selectable 功能。這會(huì)把元素返回到它的預(yù)初始化狀態(tài)。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例：

調(diào)用 destroy 方法：

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

代碼實(shí)例：

調(diào)用 disable 方法：

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

代碼實(shí)例：

調(diào)用 enable 方法：

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

代碼實(shí)例：

調(diào)用該方法：

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

代碼實(shí)例：

調(diào)用該方法：

var options = $( ".selector" ).selectable( "option" );
option( optionName, value ) jQuery (plugin only) 設(shè)置與指定的 optionName 關(guān)聯(lián)的 selectable 選項(xiàng)的值。
  • optionName
    類型：String
    描述：要設(shè)置的選項(xiàng)的名稱。
  • value
    類型：Object
    描述：要為選項(xiàng)設(shè)置的值。

代碼實(shí)例：

調(diào)用該方法：

$( ".selector" ).selectable( "option", "disabled", true );
option( options ) jQuery (plugin only) 為 selectable 設(shè)置一個(gè)或多個(gè)選項(xiàng)。
  • options
    類型：Object
    描述：要設(shè)置的 option-value 對(duì)。

代碼實(shí)例：

調(diào)用該方法：

$( ".selector" ).selectable( "option", { disabled: true } );
refresh() jQuery (plugin only) 更新每個(gè)選擇項(xiàng)元素的位置和尺寸。當(dāng) autoRefresh 選項(xiàng)被設(shè)置為 false 時(shí)，該方法可用于手動(dòng)重新計(jì)算每個(gè)選擇項(xiàng)的位置和尺寸。
  • 該方法不接受任何參數(shù)。

代碼實(shí)例：

調(diào)用 refresh 方法：

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

代碼實(shí)例：

調(diào)用 widget 方法：

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

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

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

代碼實(shí)例：

初始化帶有指定 create 回調(diào)的 selectable：

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

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

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

代碼實(shí)例：

初始化帶有指定 selected 回調(diào)的 selectable：

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

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

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

代碼實(shí)例：

初始化帶有指定 selecting 回調(diào)的 selectable：

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

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

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

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

代碼實(shí)例：

初始化帶有指定 start 回調(diào)的 selectable：

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

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

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

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

代碼實(shí)例：

初始化帶有指定 stop 回調(diào)的 selectable：

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

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

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

代碼實(shí)例：

初始化帶有指定 unselected 回調(diào)的 selectable：

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

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

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

代碼實(shí)例：

初始化帶有指定 unselecting 回調(diào)的 selectable：

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

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

$( ".selector" ).on( "selectableunselecting", function( event, ui ) {} );

實(shí)例

一個(gè)簡單的 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>

查看演示