jQuery UI API - 可放置小部件（Droppable Widget）

所屬類別

交互（Interactions）

用法

描述：為可拖拽小部件創建目標。

版本新增：1.0

依賴：

注釋：jQuery UI 可放置（Droppable）插件讓被選元素可放置（意味著它們在拖拽後接受被放置）。您可以逐個指定哪一個 draggable 會接受。

快速導航

選項 方法 事件

選項 類型 描述 默認值
accept Selector 或 Function() 控制哪個可拖拽（draggable）元素可被 droppable 接受。

支持多個類型：

  • Selector：一個選擇器，指定哪個可拖拽（draggable）元素可被 droppable 接受。
  • Function()：一個函數，將被頁面上每個 draggable 調用（作為第一個參數傳遞給函數）。如果 draggable 被接受，該函數必須返回 true。

代碼實例：

初始化帶有指定 accept 選項的 droppable：

$( ".selector" ).droppable({ accept: ".special" });
    

在初始化後，獲取或設置 accept 選項：

// getter
var accept = $( ".selector" ).droppable( "option", "accept" );

// setter
$( ".selector" ).droppable( "option", "accept", ".special" );
    
 "*"
activeClass String 如果指定了該選項，當一個可接受的 draggable 被拖拽時，class 將被添加到 droppable。

代碼實例：

初始化帶有指定 activeClass 選項的 droppable：

$( ".selector" ).droppable({ activeClass: "ui-state-highlight" });
    

在初始化後，獲取或設置 activeClass 選項：

// getter
var activeClass = $( ".selector" ).droppable( "option", "activeClass" );

// setter
$( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" );
    
 false
addClasses Boolean 如果設置為 false，將防止 ui-droppable class 被添加。這在數百個元素上調用 .droppable() 時有助於性能優化。

代碼實例：

初始化帶有指定 addClasses 選項的 droppable：

$( ".selector" ).droppable({ addClasses: false });
    

在初始化後，獲取或設置 addClasses 選項：

// getter
var addClasses = $( ".selector" ).droppable( "option", "addClasses" );

// setter
$( ".selector" ).droppable( "option", "addClasses", false );
    
 true
disabled Boolean 如果設置為 true，則禁用該 droppable。

代碼實例：

初始化帶有指定 disabled 選項的 droppable：

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

在初始化後，獲取或設置 disabled 選項：

// getter
var disabled = $( ".selector" ).droppable( "option", "disabled" );

// setter
$( ".selector" ).droppable( "option", "disabled", true );
    
 false
greedy Boolean 默認情況下，當一個元素被放置在嵌套是 droppable 上時，每個 droppable 將接收該元素。然而，通過設置該選項為 true，任何父元素的 droppable 將無法接收該元素。 drop 事件仍將照常，但會檢查 event.target 以便查看哪個 droppable 接收 draggable 元素。

代碼實例：

初始化帶有指定 greedy 選項的 droppable：

$( ".selector" ).droppable({ greedy: true });
    

在初始化後，獲取或設置 greedy 選項：

// getter
var greedy = $( ".selector" ).droppable( "option", "greedy" );

// setter
$( ".selector" ).droppable( "option", "greedy", true );
    
 false
hoverClass String 如果指定了該選項，當一個可接受 draggable 被覆蓋在 droppable 上時，class 將被添加到 droppable。

代碼實例：

初始化帶有指定 hoverClass 選項的 droppable：

$( ".selector" ).droppable({ hoverClass: "drop-hover" });
    

在初始化後，獲取或設置 hoverClass 選項：

// getter
var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" );

// setter
$( ".selector" ).droppable( "option", "hoverClass", "drop-hover" );
    
 false
scope String 用於組合配套 draggable 和 droppable 項，除了 droppable 的 accept 選項之外。一個與 droppable 帶有相同的 scope 值的 draggable 會被該 droppable 接受。

代碼實例：

初始化帶有指定 scope 選項的 droppable：

$( ".selector" ).droppable({ scope: "tasks" });
    

在初始化後，獲取或設置 scope 選項：

// getter
var scope = $( ".selector" ).droppable( "option", "scope" );

// setter
$( ".selector" ).droppable( "option", "scope", "tasks" );
    
 "default"
tolerance String 指定用於測試一個 draggable 是否覆蓋在一個 droppable 上的模式。可能的值：
  • "fit"：draggable 完全重疊在 droppable 上。
  • "intersect"：draggable 重疊在 droppable 上，兩個方向上至少 50%。
  • "pointer"：滑鼠指針重疊在 droppable 上。
  • "touch"：draggable 重疊在 droppable 上，任何數量皆可。

代碼實例：

初始化帶有指定 tolerance 選項的 droppable：

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

在初始化後，獲取或設置 tolerance 選項：

// getter
var tolerance = $( ".selector" ).droppable( "option", "tolerance" );

// setter
$( ".selector" ).droppable( "option", "tolerance", "fit" );
    
 "intersect"

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

代碼實例：

調用 destroy 方法：

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

代碼實例：

調用 disable 方法：

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

代碼實例：

調用 enable 方法：

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

代碼實例：

調用該方法：

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

代碼實例：

調用該方法：

var options = $( ".selector" ).droppable( "option" );
    
option( optionName, value ) jQuery (plugin only) 設置與指定的 optionName 關聯的 droppable 選項的值。
  • optionName
    類型：String
    描述：要設置的選項的名稱。
  • value
    類型：Object
    描述：要為選項設置的值。

代碼實例：

調用該方法：

$( ".selector" ).droppable( "option", "disabled", true );
    
option( options ) jQuery (plugin only) 為 droppable 設置一個或多個選項。
  • options
    類型：Object
    描述：要設置的 option-value 對。

代碼實例：

調用該方法：

$( ".selector" ).droppable( "option", { disabled: true } );
    
widget() jQuery 返回一個包含 droppable 元素的 jQuery 對象。
  • 該方法不接受任何參數。

代碼實例：

調用 widget 方法：

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

事件 類型 描述
activate( event, ui ) dropactivate 當一個可接受的 draggable 開始拖拽時觸發。如果您想讓 droppable 被放置時"點亮"，該選項就可以派上用場。
  • event
    類型：Event
  • ui
    類型：Object
    • draggable
      類型：jQuery
      描述：jQuery 對象，表示 draggable 元素。
    • helper
      類型：jQuery
      描述：jQuery 對象，表示被拖拽的助手（helper）。
    • position
      類型：Object
      描述：draggable 助手（helper）的當前 CSS 位置，比如 { top, left } 對象。
    • offset
      類型：Object
      描述：draggable 助手（helper）的當前偏移位置，比如 { top, left } 對象。

代碼實例：

初始化帶有指定 activate 回調的 droppable：

$( ".selector" ).droppable({
  activate: function( event, ui ) {}
});
    

綁定一個事件監聽器到 dropactivate 事件：

$( ".selector" ).on( "dropactivate", function( event, ui ) {} );
    
create( event, ui ) dropcreate 當 droppable 被創建時觸發。
  • event
    類型：Event
  • ui
    類型：Object

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

代碼實例：

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

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

綁定一個事件監聽器到 dropcreate 事件：

$( ".selector" ).on( "dropcreate", function( event, ui ) {} );
    
deactivate( event, ui ) dropdeactivate 當一個可接受的 draggable 停止拖拽時觸發。
  • event
    類型：Event
  • ui
    類型：Object
    • draggable
      類型：jQuery
      描述：jQuery 對象，表示 draggable 元素。
    • helper
      類型：jQuery
      描述：jQuery 對象，表示被拖拽的助手（helper）。
    • position
      類型：Object
      描述：draggable 助手（helper）的當前 CSS 位置，比如 { top, left } 對象。
    • offset
      類型：Object
      描述：draggable 助手（helper）的當前偏移位置，比如 { top, left } 對象。

代碼實例：

初始化帶有指定 deactivate 回調的 droppable：

$( ".selector" ).droppable({
  deactivate: function( event, ui ) {}
});
    

綁定一個事件監聽器到 dropdeactivate 事件：

$( ".selector" ).on( "dropdeactivate", function( event, ui ) {} );
    
drop( event, ui ) drop 當一個可接受的 draggable 被放置在 droppable（基於 tolerance 選項）上時觸發。
  • event
    類型：Event
  • ui
    類型：Object
    • draggable
      類型：jQuery
      描述：jQuery 對象，表示 draggable 元素。
    • helper
      類型：jQuery
      描述：jQuery 對象，表示被拖拽的助手（helper）。
    • position
      類型：Object
      描述：draggable 助手（helper）的當前 CSS 位置，比如 { top, left } 對象。
    • offset
      類型：Object
      描述：draggable 助手（helper）的當前偏移位置，比如 { top, left } 對象。

代碼實例：

初始化帶有指定 drop 回調的 droppable：

$( ".selector" ).droppable({
  drop: function( event, ui ) {}
});
    

綁定一個事件監聽器到 drop 事件：

$( ".selector" ).on( "drop", function( event, ui ) {} );
    
out( event, ui ) dropout 當 droppable 被拖拽出 droppable（基於 tolerance 選項）時觸發。
  • event
    類型：Event
  • ui
    類型：Object

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

代碼實例：

初始化帶有指定 out 回調的 droppable：

$( ".selector" ).droppable({
  out: function( event, ui ) {}
});
    

綁定一個事件監聽器到 dropout 事件：

$( ".selector" ).on( "dropout", function( event, ui ) {} );
    
over( event, ui ) dropover 當一個可接受的 draggable 被拖拽在 droppable（基於 tolerance 選項）上時觸發。
  • event
    類型：Event
  • ui
    類型：Object
    • draggable
      類型：jQuery
      描述：jQuery 對象，表示 draggable 元素。
    • helper
      類型：jQuery
      描述：jQuery 對象，表示被拖拽的助手（helper）。
    • position
      類型：Object
      描述：draggable 助手（helper）的當前 CSS 位置，比如 { top, left } 對象。
    • offset
      類型：Object
      描述：draggable 助手（helper）的當前偏移位置，比如 { top, left } 對象。

代碼實例：

初始化帶有指定 over 回調的 droppable：

$( ".selector" ).droppable({
  over: function( event, ui ) {}
});
    

綁定一個事件監聽器到 dropover 事件：

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

實例

一對 draggable 和 droppable 元素。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>可放置小部件（Droppable Widget）演示</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <style>
  #draggable {
    width: 100px;
    height: 100px;
    background: #ccc;
  }
  #droppable {
    position: absolute;
    left: 250px;
    top: 0;
    width: 125px;
    height: 125px;
    background: #999;
    color: #fff;
    padding: 10px;
  }
  </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>

<div id="droppable">請放置到這裏！</div>
<div id="draggable">請拖拽我！</div>

<script>
$( "#draggable" ).draggable();
$( "#droppable" ).droppable({
  drop: function() {
    alert( "dropped" );
  }
});
</script>

</body>
</html>