jQuery UI Draggable 完整参考

介绍

jQuery UI Draggable 是一款基于 jQuery UI 的插件，用于实现元素的拖拽功能。它提供了丰富的配置选项和事件处理函数，可以轻松实现各种交互效果。

安装

CDN 安装

<!-- jQuery 依赖 -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

<!-- jQuery UI 官方 CDN -->
<link rel="stylesheet" href="https://code.jquery.com/ui/1.13.0/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/ui/1.13.0/jquery-ui.min.js"></script>

npm 安装

npm install jquery-ui

基本用法

HTML 结构

<div id="draggable">
  拖拽我试试
</div>

调用方法

$("#draggable").draggable();

配置选项

以下是常用的配置选项：

| 选项 | 类型 | 默认值 | 描述 | | ---------------- | -------- | ---------------- | ------------------------------------------------------------ | | addClasses | 布尔值 | true | 是否在拖拽时给元素添加 ui-draggable-dragging 类。 | | appendTo | 字符串 | 'parent' | 拖拽时元素要附加到的容器。 | | axis | 字符串 | false | 拖拽时元素移动的方向。可选值为 'x'、'y' 和 false。 | | cancel | 字符串 | ':input, button' | 防止拖拽时某些元素响应。 | | containment | 字符串或对象 | false | 拖拽时元素的限制范围。可设置为父元素、可滚动元素或绝对定位元素。 | | cursor | 字符串 | 'auto' | 鼠标指针样式。 | | cursorAt | 对象 | { top: 0, left: 0 } | 鼠标指针相对于元素的位置。 | | delay | 整数 | 0 | 开始拖拽的延迟时间，单位毫秒。 | | disabled | 布尔值 | false | 是否禁用 Draggable。 | | distance | 整数 | 1 | 开始拖拽的触发距离，单位像素。 | | grid | 数组 | false | 拖拽时元素按网格对齐。值为 [x, y]。 | | handle | 字符串或布尔值 | false | 元素内的句柄，用于启用拖拽。 | | helper | 字符串或函数 | 'original' | 拖拽时显示的辅助元素。可设置为 'clone' 或自定义函数。参考下文。 | | opacity | 数字 | false | 拖拽时元素的不透明度。值为 0 到 1 的小数。 | | refreshPositions | 布尔值 | false | 拖拽时是否重新计算元素位置。 | | revert | 布尔值或数字 | false | 拖拽结束后元素是否返回原位置。 | | revertDuration | 整数 | 500 | 元素返回原位置的动画时间，单位毫秒。 | | scope | 字符串 | 'default' | 用于指定拖拽元素所属的作用域。 | | scroll | 布尔值 | true | 拖拽时是否自动滚动容器。 | | scrollSensitivity | 整数 | 20 | 自动滚动容器的触发距离，单位像素。 | | scrollSpeed | 整数 | 20 | 自动滚动容器的速度，数值越大滚动越快。 | | snap | 布尔值或字符串 | false | 拖拽时是否吸附到网格或元素边缘。 | | snapMode | 字符串 | 'both' | 吸附模式。可选值为 'both'、'inner' 和 'outer'。 | | snapTolerance | 整数 | 20 | 吸附触发的容差距离，单位像素。 | | stack | 字符串 | false | 元素在拖拽时的堆叠顺序。 | | zIndex | 整数 | false | 元素在拖拽时的层级。 |

事件处理

以下是 Draggable 支持的事件处理函数：

| 事件名 | 描述 | | --------------- | ------------------------------------------------------------ | | create | 初始化 Draggable 时触发。 | | start | 开始拖拽时触发。 | | drag | 拖拽过程中触发。 | | stop | 停止拖拽时触发。 | | activate | 另一个拖拽元素进入当前元素的作用域时触发。 | | deactivate | 另一个拖拽元素离开当前元素的作用域时触发。 | | over | 另一个拖拽元素进入当前元素时触发。 | | out | 另一个拖拽元素离开当前元素时触发。 | | beforeStart | 拖拽开始前触发，如果返回值为 false 可以阻止拖拽的发生。 | | beforeStop | 拖拽停止前触发，如果返回值为 false 可以阻止元素返回原位置。 | | beforeRevert | 元素回到原位置前触发，如果返回值为 false 可以阻止元素返回原位置。 | | dragStart | 开始拖拽时触发，可以在该事件处理函数中实现自定义的辅助元素。参考下文。 | | dragStop | 停止拖拽时触发，可以在该事件处理函数中实现自定义的元素归位动画。参考下文。 | | dragging | 拖拽过程中触发，可以在该事件处理函数中实现自定义的吸附行为。参考下文。 | | refreshPositions | 重新计算元素位置时触发。 |

辅助元素和元素归位动画

在 helper 和 revert 选项中分别可以自定义辅助元素和元素归位动画，可以通过 dragStart 和 dragStop 事件中的参数获取当前拖拽的元素的相关信息，例如位置、宽高等。

自定义辅助元素

$("#draggable").draggable({
  helper: function() {
    return $("<div class='my-helper'>拖拽中</div>");
  },
  dragStart: function(event, ui) {
    $('.my-helper').appendTo('body'); // 将辅助元素动态加入 DOM 树
  }
});

自定义元素归位动画

$("#draggable").draggable({
  revert: true,
  revertDuration: 200,
  dragStop: function(event, ui) {
    $(this).animate({ // 元素归位动画
      top: ui.originalPosition.top,
      left: ui.originalPosition.left
    }, 200);
  }
});

自定义吸附行为

$("#draggable").draggable({
  snap: ".my-snap",
  snapping: true,
  snapTolerance: 20,
  dragging: function(event, ui) {
    var snapElem = $(this).data("ui-draggable").snapElements;
    if (snapElem.length > 0) {
      var snapTop = snapElem[0].top;
      var snapLeft = snapElem[0].left;
      ui.position.top = snapTop;
      ui.position.left = snapLeft;
    }
  }
});

示例

HTML 结构

<div id="container" style="position: relative; height: 400px;">
  <div id="draggable1" class="draggable"></div>
  <div id="draggable2" class="draggable"></div>
  <div id="draggable3" class="draggable"></div>
  <div id="snap1" class="my-snap"></div>
  <div id="snap2" class="my-snap"></div>
  <div id="cancel1" class="my-cancel">
    <input type="text">
    <button>点击</button>
  </div>
</div>

CSS 样式

.draggable {
  position: absolute;
  width: 100px;
  height: 100px;
  background-color: #ccc;
  border: 1px solid #999;
  cursor: move;
}

.my-snap {
  position: absolute;
  top: 50px;
  left: 50px;
  width: 100px;
  height: 100px;
  border: 1px solid #f00;
}

.my-cancel input,
.my-cancel button {
  margin: 10px;
}

JavaScript 代码

$(".draggable").draggable({
  addClasses: false,
  containment: "#container",
  delay: 200,
  distance: 10,
  handle: ".handle",
  helper: "clone",
  opacity: 0.5,
  revert: true,
  revertDuration: 500,
  stack: ".draggable",
  zIndex: 999
});

$("#draggable1").on("create beforeStart start drag", function(event, ui) {
  console.log(event.type, ui.position);
});

$("#draggable1").on("stop", function(event, ui) {
  console.log(event.type, ui.position);
});

$("#draggable2").draggable({
  axis: "x",
  cursor: "grabbing",
  cursorAt: { top: 50, left: 50 },
  grid: [20, 20],
  scroll: false
});

$("#draggable3").draggable({
  axis: "y",
  containment: "parent",
  scroll: true,
  snap: ".my-snap",
  snapping: true,
  snapTolerance: 20,
  dragging: function(event, ui) {
    var snapElem = $(this).data("ui-draggable").snapElements;
    if (snapElem.length > 0) {
      var snapTop = snapElem[0].top;
      var snapLeft = snapElem[0].left;
      ui.position.top = snapTop;
      ui.position.left = snapLeft;
    }
  },
  start: function(event, ui) {
    $(this).addClass("highlight");
  },
  stop: function(event, ui) {
    $(this).removeClass("highlight");
  }
});

$(".my-cancel").draggable({
  cancel: "input,button"
});