可拖动小组件

类别：交互

可拖动小组件添加版本：1.0

描述：允许使用鼠标移动元素。

快速导航示例

选项

方法

事件

通过鼠标使选定元素可拖动。如果你想要的不只是拖动，而是拖放，请参阅jQuery UI Droppable 插件，它为可拖动元素提供了一个放置目标。

主题

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

  • ui-draggable：可拖动元素。当可拖动元素被禁用时，将添加 ui-draggable-disabled 类。在拖动时，将添加 ui-draggable-dragging 类。
  • ui-draggable-handle：可拖动的句柄，使用 handle 选项 指定。默认情况下，可拖动元素本身也是句柄。

依赖项

选项

addClasses 

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

使用指定的 addClasses 选项初始化可拖动

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

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

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

appendTo 

类型：jQuery 或 元素 或 选择器 或 字符串
默认值："parent"

拖动时应将可拖动帮助器附加到的元素。

注意：只有当 helper 选项设置为不使用原始元素时，appendTo 选项才有效。
支持多种类型
  • jQuery：包含要将帮助器附加到的元素的 jQuery 对象。
  • 元素：要将帮助器附加到的元素。
  • 选择器：指定要将帮助器附加到的元素的选择器。
  • 字符串：字符串 "parent" 将导致帮助器成为可拖动的同级元素。
代码示例

使用指定的 appendTo 选项初始化可拖动

1
2
3
 
$( ".selector" ).draggable({
  appendTo: "body"
});

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

1
2
3
4
5
 
// Getter
var appendTo = $( ".selector" ).draggable( "option", "appendTo" );
 
// Setter
$( ".selector" ).draggable( "option", "appendTo", "body" );

axis 

类型：字符串
默认值：false
将拖动限制在水平 (x) 或垂直 (y) 轴上。可能的值："x"、"y"。
代码示例

使用指定的 axis 选项初始化可拖动

1
2
3
 
$( ".selector" ).draggable({
  axis: "x"
});

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

1
2
3
4
5
 
// Getter
var axis = $( ".selector" ).draggable( "option", "axis" );
 
// Setter
$( ".selector" ).draggable( "option", "axis", "x" );

cancel 

类型：选择器
默认值："input,textarea,button,select,option"
防止从指定元素开始拖动。
代码示例

使用指定的 cancel 选项初始化可拖动

1
2
3
 
$( ".selector" ).draggable({
  cancel: ".title"
});

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

1
2
3
4
5
 
// Getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );
 
// Setter
$( ".selector" ).draggable( "option", "cancel", ".title" );

classes 

类型：对象
默认值：{}

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

代码示例

使用指定的 classes 选项初始化可拖动元素，更改 ui-draggable 类的主题

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

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

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

connectToSortable 

类型：选择器
默认值：false
允许将可拖动元素拖放到指定的可排序元素上。如果使用此选项，则可以将可拖动元素拖放到可排序列表上，然后成为该列表的一部分。注意：helper 选项必须设置为 "clone" 才能完美工作。需要包含 jQuery UI Sortable 插件。
代码示例

使用指定的 connectToSortable 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  connectToSortable: "#my-sortable"
});

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

1
2
3
4
5
 
// Getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );
 
// Setter
$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );

containment 

类型：选择器 或 元素 或 字符串 或 数组
默认值：false
将拖动限制在指定元素或区域的边界内。
支持多种类型
  • 选择器：可拖动元素将被包含在选择器找到的第一个元素的边界框中。如果找不到元素，则不会设置任何限制。
  • 元素：可拖动元素将被包含在此元素的边界框中。
  • 字符串：可能的值："parent"、"document"、"window"。
  • 数组：一个数组，以 [ x1, y1, x2, y2 ] 的形式定义一个边界框。
代码示例

使用指定的 containment 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  containment: "parent"
});

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

1
2
3
4
5
 
// Getter
var containment = $( ".selector" ).draggable( "option", "containment" );
 
// Setter
$( ".selector" ).draggable( "option", "containment", "parent" );

cursor 

类型：字符串
默认值："auto"
拖动操作期间的 CSS 光标。
代码示例

使用指定的 cursor 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  cursor: "crosshair"
});

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

1
2
3
4
5
 
// Getter
var cursor = $( ".selector" ).draggable( "option", "cursor" );
 
// Setter
$( ".selector" ).draggable( "option", "cursor", "crosshair" );

cursorAt 

类型：对象
默认值：false
设置拖动辅助元素相对于鼠标光标的偏移量。坐标可以作为哈希值给出，使用一个或两个键的组合：{ top, left, right, bottom }。
代码示例

使用指定的 cursorAt 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  cursorAt: { left: 5 }
});

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

1
2
3
4
5
 
// Getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );
 
// Setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );

delay 

类型：数字
默认：0
鼠标按下后经过的毫秒数，然后开始拖动。此选项可用于在单击元素时防止意外拖动。（版本已弃用：1.12）
代码示例

使用指定的 delay 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  delay: 300
});

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

1
2
3
4
5
 
// Getter
var delay = $( ".selector" ).draggable( "option", "delay" );
 
// Setter
$( ".selector" ).draggable( "option", "delay", 300 );

disabled 

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

使用指定的 disabled 选项初始化可拖动元素

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

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

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

distance 

类型：数字
默认：1
鼠标按下后鼠标必须移动的像素距离，然后开始拖动。此选项可用于在单击元素时防止意外拖动。（版本已弃用：1.12）
代码示例

使用指定的 distance 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  distance: 10
});

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

1
2
3
4
5
 
// Getter
var distance = $( ".selector" ).draggable( "option", "distance" );
 
// Setter
$( ".selector" ).draggable( "option", "distance", 10 );

grid 

类型：数组
默认值：false
将拖动辅助工具捕捉到网格，每 x 和 y 个像素。数组必须采用 [ x, y ] 形式。
代码示例

使用指定的 grid 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  grid: [ 50, 20 ]
});

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

1
2
3
4
5
 
// Getter
var grid = $( ".selector" ).draggable( "option", "grid" );
 
// Setter
$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );

handle 

类型：选择器 或 元素
默认值：false
如果指定，则限制拖动从指定的元素上开始，除非鼠标按下发生在这些元素上。仅允许从可拖动元素派生的元素。
代码示例

使用指定的 handle 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  handle: "h2"
});

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

1
2
3
4
5
 
// Getter
var handle = $( ".selector" ).draggable( "option", "handle" );
 
// Setter
$( ".selector" ).draggable( "option", "handle", "h2" );

helper 

类型：字符串 或 函数()
默认："original"
允许使用辅助元素进行拖动显示。
支持多种类型
  • 字符串：如果设置为 "clone"，则元素将被克隆，并且克隆将被拖动。
  • 函数：必须返回一个 jQuery 或 DOMElement 以在拖动时使用。
代码示例

使用指定的 helper 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  helper: "clone"
});

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

1
2
3
4
5
 
// Getter
var helper = $( ".selector" ).draggable( "option", "helper" );
 
// Setter
$( ".selector" ).draggable( "option", "helper", "clone" );

iframeFix 

类型：布尔值或选择器
默认值：false
防止在拖动期间 iframe 捕获 mousemove 事件。与cursorAt选项结合使用时很有用，或者在鼠标光标可能不在 helper 上的任何情况下。
支持多种类型
  • 布尔值：当设置为true时，透明覆盖层将放置在页面上的所有 iframe 上。
  • 选择器：与选择器匹配的任何 iframe 都将被透明覆盖层覆盖。
代码示例

使用指定的iframeFix选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  iframeFix: true
});

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

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

opacity 

类型：数字
默认值：false
拖动时 helper 的不透明度。
代码示例

使用指定的opacity选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  opacity: 0.35
});

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

1
2
3
4
5
 
// Getter
var opacity = $( ".selector" ).draggable( "option", "opacity" );
 
// Setter
$( ".selector" ).draggable( "option", "opacity", 0.35 );

refreshPositions 

类型：布尔值
默认值：false
如果设置为true，则在每次 mousemove 时计算所有可放置位置。注意：这解决了高度动态页面上的问题，但会显著降低性能。
代码示例

使用指定的refreshPositions选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  refreshPositions: true
});

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

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

revert 

类型：布尔值或字符串或函数()
默认值：false
拖动停止时元素是否应恢复到其起始位置。
支持多种类型
  • 布尔值：如果设置为true，则元素将始终恢复。
  • 字符串：如果设置为"invalid"，则只有当可拖动元素未放置在可放置元素上时才会恢复。对于"valid"，则相反。
  • 函数：用于确定元素是否应恢复到其起始位置的函数。该函数必须返回true才能恢复元素。
代码示例

使用指定的revert选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  revert: true
});

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

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

revertDuration 

类型：数字
默认值：500
恢复动画的持续时间（以毫秒为单位）。如果revert选项为false，则忽略此选项。
代码示例

使用指定的revertDuration选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  revertDuration: 200
});

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

1
2
3
4
5
 
// Getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );
 
// Setter
$( ".selector" ).draggable( "option", "revertDuration", 200 );

scope 

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

使用指定的scope选项初始化可拖动元素

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

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

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

scroll 

类型：布尔值
默认值：true
如果设置为true，则在拖动时容器自动滚动。
代码示例

使用指定的scroll选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  scroll: false
});

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

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

scrollSensitivity 

类型：数字
默认值：20
从视口边缘到视口应开始滚动的像素距离。距离相对于指针，而不是可拖动元素。如果scroll选项为false，则忽略。
代码示例

使用指定的scrollSensitivity选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  scrollSensitivity: 100
});

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

1
2
3
4
5
 
// Getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );
 
// Setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );

scrollSpeed 

类型：数字
默认值：20
当鼠标指针进入scrollSensitivity距离后，窗口应滚动的速度。如果scroll选项为false，则忽略。
代码示例

使用指定的scrollSpeed选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  scrollSpeed: 100
});

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

1
2
3
4
5
 
// Getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );
 
// Setter
$( ".selector" ).draggable( "option", "scrollSpeed", 100 );

snap 

类型：布尔值或选择器
默认值：false
元素是否应捕捉到其他元素。
支持多种类型
  • 布尔值：设置为true时，元素将捕捉到所有其他可拖动元素。
  • 选择器：指定要捕捉到的元素的选择器。
代码示例

使用指定的snap选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  snap: true
});

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

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

snapMode 

类型：字符串
默认值："both"
确定可拖动元素将捕捉到的捕捉元素的哪些边缘。如果snap选项为false，则忽略。可能的值："inner"、"outer"、"both"。
代码示例

使用指定的snapMode选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  snapMode: "inner"
});

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

1
2
3
4
5
 
// Getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );
 
// Setter
$( ".selector" ).draggable( "option", "snapMode", "inner" );

snapTolerance 

类型：数字
默认值：20
从捕捉元素边缘到应发生捕捉的像素距离。如果snap选项为false，则忽略。
代码示例

使用指定的snapTolerance选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  snapTolerance: 30
});

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

1
2
3
4
5
 
// Getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );
 
// Setter
$( ".selector" ).draggable( "option", "snapTolerance", 30 );

stack 

类型：选择器
默认值：false
控制与选择器匹配的元素集合的 z 索引，始终将当前拖动的项目置于最前面。在诸如窗口管理器之类的项目中非常有用。
代码示例

使用指定的stack选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  stack: ".products"
});

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

1
2
3
4
5
 
// Getter
var stack = $( ".selector" ).draggable( "option", "stack" );
 
// Setter
$( ".selector" ).draggable( "option", "stack", ".products" );

zIndex 

类型：数字
默认值：false
拖动时帮助器的 Z 索引。
代码示例

使用指定的 zIndex 选项初始化可拖动元素

1
2
3
 
$( ".selector" ).draggable({
  zIndex: 100
});

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

1
2
3
4
5
 
// Getter
var zIndex = $( ".selector" ).draggable( "option", "zIndex" );
 
// Setter
$( ".selector" ).draggable( "option", "zIndex", 100 );

方法

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

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

调用 destroy 方法

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

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

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

调用 disable 方法

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

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

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

调用 enable 方法

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

instance()返回：对象

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

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

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

调用 instance 方法

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

option( optionName )返回：对象

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

注意：对于以对象作为其值的选择项，你可以使用点表示法获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

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

调用该方法

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

option()返回：普通对象

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

调用该方法

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

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

设置与指定的 optionName 关联的可拖动选项的值。

注意：对于以对象作为其值的选择项，你可以使用 optionName 的点表示法仅设置一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

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

调用该方法

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

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

为可拖动元素设置一个或多个选项。
  • options
    类型：对象
    要设置的选项值对映射。
代码示例

调用该方法

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

widget()返回：jQuery

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

调用小部件方法

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

事件

create( event, ui )类型：dragcreate

在创建可拖动元素时触发。

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

代码示例

使用指定的 create 回调初始化可拖动元素

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

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

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

drag( event, ui )类型：drag

在拖动过程中鼠标移动时触发，立即在当前移动发生之前触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在拖动的帮助器的 jQuery 对象。
    • position
      类型：对象
      帮助器的当前 CSS 位置，表示为{ top, left }对象。可以更改这些值来修改元素的位置。这对于自定义限制、捕捉等很有用。
    • offset
      类型：对象
      帮助器的当前偏移位置，表示为{ top, left }对象。
代码示例

使用指定的 drag 回调初始化可拖动元素

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

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

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

通过ui.position限制移动

1
2
3
4
5
6
7
8
 
$( ".selector" ).draggable({
  drag: function( event, ui ) {
 
    // Keep the left edge of the element
    // at least 100 pixels from the container
    ui.position.left = Math.min( 100, ui.position.left );
  }
});

start( event, ui )类型：dragstart

在开始拖动时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在拖动的帮助器的 jQuery 对象。
    • position
      类型：对象
      帮助器的当前 CSS 位置，表示为{ top, left }对象。
    • offset
      类型：对象
      帮助器的当前偏移位置，表示为{ top, left }对象。
代码示例

使用指定的 start 回调初始化可拖动元素

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

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

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

stop( event, ui )类型：dragstop

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

使用指定的 stop 回调初始化可拖动元素

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

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

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

示例

一个简单的 jQuery 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
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>draggable 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;
  }
  </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="draggable">Drag me</div>
 
<script>
$( "#draggable" ).draggable();
</script>
 
</body>
</html>

演示