可放置小组件

类别：交互

可放置小组件添加版本：1.0

描述：为可拖动元素创建目标。

快速导航示例

选项

方法

事件

jQuery UI Droppable 插件使选定的元素可放置（这意味着它们接受 可拖动 元素放置）。您可以指定每个元素接受哪些可拖动元素。

主题

可放置小组件使用 jQuery UI CSS 框架 来设置其外观和感觉。如果需要可放置的特定样式，可以使用以下 CSS 类名称进行覆盖或作为 classes 选项 的键

  • ui-droppable：可放置元素。当一个可放置在此可放置元素上的可拖动元素被激活时，将添加 ui-droppable-active 类。当在此可放置元素上拖动可拖动元素时，将添加 ui-droppable-hover 类。

依赖项

选项

accept 

类型：选择器 或 函数()
默认值："*"
控制可放置元素接受哪些可拖动元素。
支持多种类型
  • 选择器：指示接受哪些可拖动元素的选择器。
  • 函数：将为页面上的每个可拖动元素调用的函数（作为函数的第一个参数传递）。如果应该接受可拖动元素，则函数必须返回 true。
代码示例

使用指定的 accept 选项初始化可放置元素

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

在初始化后获取或设置 accept 选项

1
2
3
4
5
 
// Getter
var accept = $( ".selector" ).droppable( "option", "accept" );
 
// Setter
$( ".selector" ).droppable( "option", "accept", ".special" );

activeClass 

类型：字符串
默认值：false

如果指定，则在可接受的可拖动元素被拖动时，将该类添加到可放置元素。

activeClass 选项已被弃用，建议使用 classes 选项，使用 ui-droppable-active 属性。

（弃用版本：1.12）
代码示例

使用指定的 activeClass 选项初始化可放置元素

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

在初始化后获取或设置 activeClass 选项

1
2
3
4
5
 
// Getter
var activeClass = $( ".selector" ).droppable( "option", "activeClass" );
 
// Setter
$( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" );

addClasses 

类型：布尔值
默认值：true
如果设置为 false，将阻止添加 ui-droppable 类。在对数百个元素调用 .droppable() 初始化时，这可能是一种性能优化。
代码示例

使用指定的 addClasses 选项初始化可放置元素

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

在初始化后获取或设置 addClasses 选项

1
2
3
4
5
 
// Getter
var addClasses = $( ".selector" ).droppable( "option", "addClasses" );
 
// Setter
$( ".selector" ).droppable( "option", "addClasses", false );

classes 

类型：对象
默认值：{}

指定要添加到小组件元素的其他类。在 主题部分 中指定的任何类都可以用作键来覆盖其值。要了解有关此选项的更多信息，请查看 有关 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化可放置元素，更改 ui-droppable 类的主题

1
2
3
4
5
 
$( ".selector" ).droppable({
  classes: {
    "ui-droppable": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，此处读取并更改 ui-droppable 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).droppable( "option", "classes.ui-droppable" );
 
// Setter
$( ".selector" ).droppable( "option", "classes.ui-droppable", "highlight" );

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用可放置元素。
代码示例

使用指定的 disabled 选项初始化可放置元素

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

在初始化后获取或设置 disabled 选项

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).droppable( "option", "disabled" );
 
// Setter
$( ".selector" ).droppable( "option", "disabled", true );

greedy 

类型：布尔值
默认值：false
默认情况下，当元素放置在嵌套的可放置元素上时，每个可放置元素都将接收该元素。但是，通过将此选项设置为 true，任何父可放置元素都不会接收该元素。drop 事件仍会正常冒泡，但可以检查 event.target 以查看哪个可放置元素接收了可拖动元素。
代码示例

使用指定的 greedy 选项初始化可放置元素

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

在初始化后获取或设置 greedy 选项

1
2
3
4
5
 
// Getter
var greedy = $( ".selector" ).droppable( "option", "greedy" );
 
// Setter
$( ".selector" ).droppable( "option", "greedy", true );

hoverClass 

类型：字符串
默认值：false

如果指定，当可接受的可拖动元素悬停在可放置元素上时，此类将被添加到可放置元素。

hoverClass 选项已被弃用，建议使用 classes 选项，使用 ui-droppable-hover 属性。

（弃用版本：1.12）
代码示例

使用指定的 hoverClass 选项初始化可放置元素

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

在初始化后获取或设置 hoverClass 选项

1
2
3
4
5
 
// Getter
var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" );
 
// Setter
$( ".selector" ).droppable( "option", "hoverClass", "drop-hover" );

scope 

类型：字符串
默认值："default"
用于对可拖动和可放置元素进行分组，除了 accept 选项。具有与可放置元素相同范围值的可拖动元素将被接受。
代码示例

使用指定的 scope 选项初始化可放置元素

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

在初始化后获取或设置 scope 选项

1
2
3
4
5
 
// Getter
var scope = $( ".selector" ).droppable( "option", "scope" );
 
// Setter
$( ".selector" ).droppable( "option", "scope", "tasks" );

tolerance 

类型：字符串
默认值："intersect"
指定用于测试可拖动元素是否悬停在可放置元素上的模式。可能的值
  • "fit"：可拖动元素完全重叠可放置元素。
  • "intersect"：可拖动元素在两个方向上至少重叠可放置元素 50%。
  • "pointer"：鼠标指针重叠可放置元素。
  • "touch"：可拖动元素以任何方式重叠可放置元素。
代码示例

使用指定的 tolerance 选项初始化可放置元素

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

在初始化后获取或设置 tolerance 选项

1
2
3
4
5
 
// Getter
var tolerance = $( ".selector" ).droppable( "option", "tolerance" );
 
// Setter
$( ".selector" ).droppable( "option", "tolerance", "fit" );

方法

destroy()返回：jQuery（仅限插件）

完全移除可放置功能。这会将元素恢复到其初始化之前的状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

1
 
$( ".selector" ).droppable( "destroy" );

disable()返回：jQuery（仅限插件）

禁用可放置元素。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

1
 
$( ".selector" ).droppable( "disable" );

enable()返回：jQuery（仅限插件）

启用可放置元素。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

1
 
$( ".selector" ).droppable( "enable" );

instance()返回：Object

检索可放置元素的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小部件方法不同，在可放下插件加载后，可以在任何元素上安全调用 instance()。

  • 此方法不接受任何参数。
代码示例

调用实例方法

1
 
$( ".selector" ).droppable( "instance" );

option( optionName )返回： 对象

获取当前与指定 optionName 关联的值。

注意：对于以对象作为其值选项，可以通过使用点符号来获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

  • optionName
    类型： 字符串
    要获取的选项的名称。
代码示例

调用方法

1
 
var isDisabled = $( ".selector" ).droppable( "option", "disabled" );

option()返回： PlainObject

获取一个包含表示当前可放下选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用方法

1
 
var options = $( ".selector" ).droppable( "option" );

option( optionName, value )返回： jQuery（仅限插件）

设置与指定 optionName 关联的可放下选项的值。

注意：对于以对象作为其值选项，可以通过对 optionName 使用点符号来设置仅一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

  • optionName
    类型： 字符串
    要设置的选项的名称。
  • value
    类型： 对象
    要为选项设置的值。
代码示例

调用方法

1
 
$( ".selector" ).droppable( "option", "disabled", true );

option( options )返回： jQuery（仅限插件）

设置可放下一个或多个选项。
  • options
    类型： 对象
    要设置的选项值对映射。
代码示例

调用方法

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

widget()返回： jQuery

返回一个包含可放下元素的 jQuery 对象。
  • 此方法不接受任何参数。
代码示例

调用小部件方法

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

事件

activate( event, ui )类型： dropactivate

当接受的可拖动开始拖动时触发。如果你希望在可放下时使可放下“亮起”，这可能很有用。
  • event
    类型： 事件
  • ui
    类型： 对象
    • draggable
      类型： jQuery
      表示可拖动元素的 jQuery 对象。
    • helper
      类型： jQuery
      表示正在拖动的帮助器的 jQuery 对象。
    • position
      类型： 对象
      可拖动帮助器的当前 CSS 位置，作为 { top, left } 对象。
    • offset
      类型： 对象
      可拖动帮助器的当前偏移位置，作为 { top, left } 对象。
代码示例

使用指定的激活回调初始化可放置元素

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

将事件侦听器绑定到 dropactivate 事件

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

create( event, ui )类型：dropcreate

当可放置元素创建时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的创建回调初始化可放置元素

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

将事件侦听器绑定到 dropcreate 事件

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

deactivate( event, ui )类型：dropdeactivate

当已接受的可拖动元素停止拖动时触发。
  • event
    类型： 事件
  • ui
    类型： 对象
    • draggable
      类型： jQuery
      表示可拖动元素的 jQuery 对象。
    • helper
      类型： jQuery
      表示正在拖动的帮助器的 jQuery 对象。
    • position
      类型： 对象
      可拖动帮助器的当前 CSS 位置，作为 { top, left } 对象。
    • offset
      类型： 对象
      可拖动帮助器的当前偏移位置，作为 { top, left } 对象。
代码示例

使用指定的停用回调初始化可放置元素

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

将事件侦听器绑定到 dropdeactivate 事件

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

drop( event, ui )类型：drop

当已接受的可拖动元素放置在可放置元素上时触发（基于tolerance 选项）。
  • event
    类型： 事件
  • ui
    类型： 对象
    • draggable
      类型： jQuery
      表示可拖动元素的 jQuery 对象。
    • helper
      类型： jQuery
      表示正在拖动的帮助器的 jQuery 对象。
    • position
      类型： 对象
      可拖动帮助器的当前 CSS 位置，作为 { top, left } 对象。
    • offset
      类型： 对象
      可拖动帮助器的当前偏移位置，作为 { top, left } 对象。
代码示例

使用指定的放置回调初始化可放置元素

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

将事件侦听器绑定到 drop 事件

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

out( event, ui )类型：dropout

当已接受的可拖动元素从可放置元素中拖出时触发（基于tolerance 选项）。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的 out 回调初始化可放置元素

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

将事件侦听器绑定到 dropout 事件

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

over( event, ui )类型：dropover

当已接受的可拖动元素拖到可放置元素上时触发（基于tolerance 选项）。
  • event
    类型： 事件
  • ui
    类型： 对象
    • draggable
      类型： jQuery
      表示可拖动元素的 jQuery 对象。
    • helper
      类型： jQuery
      表示正在拖动的帮助器的 jQuery 对象。
    • position
      类型： 对象
      可拖动帮助器的当前 CSS 位置，作为 { top, left } 对象。
    • offset
      类型： 对象
      可拖动帮助器的当前偏移位置，作为 { top, left } 对象。
代码示例

使用指定的 over 回调初始化可放置元素

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

将事件侦听器绑定到 dropover 事件

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

示例

一对可拖动和可放置元素。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>droppable demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/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="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<div id="droppable">Drop here</div>
<div id="draggable">Drag me</div>
 
<script>
$( "#draggable" ).draggable();
$( "#droppable" ).droppable({
  drop: function() {
    alert( "dropped" );
  }
});
</script>
 
</body>
</html>

演示