jQuery UI
jQuery UI 简介 jQuery UI 下载 jQuery UI 使用 jQuery UI 定制 jQuery UI 工作原理 jQuery UI 主题 jQuery UI ThemeRoller jQuery UI CSS 框架 API jQuery UI 设计主题 jQuery UI 部件库 jQuery UI 扩展小部件 jQuery UI 小部件方法调用 jQuery UI 为什么使用部件库 jQuery UI 如何使用部件库 jQuery UI API 文档 API 类别 - 特效 API 类别 - 特效核心 API 类别 - 交互 API 类别 - 方法重载 API 类别 - 方法 API 类别 - 选择器 API 类别 - 主题 API 类别 - UI 核心 API 类别 - 实用工具 API 类别 - 小部件
首页 > JavaScript > jQuery UI

可拖拽小部件（Draggable Widget）

jQuery UI API - 可拖拽小部件（Draggable Widget）

所属类别

交互（Interactions）

用法

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

版本新增：1.0

依赖：


注释：让被选元素可被鼠标拖拽。如果您不只是拖拽，而是拖拽 & 放置，请查看 jQuery UI 可放置（Droppable）插件，为可拖拽元素提供了一个放置目标。

快速导航

选项 方法 事件

选项 类型 描述 默认值
addClasses Boolean 如果设置为false，将阻止ui-draggableclass 被添加。当在数百个元素上调用.draggable()时，这么设置有利于性能优化。

代码实例：

初始化带有指定addClasses选项的 draggable： 

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

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

// getter
var addClasses = $( ".selector" ).draggable( "option", "addClasses" );
 
// setter
$( ".selector" ).draggable( "option", "addClasses", false );
true
appendTo jQuery 或 Element 或 Selector 或 String 当拖拽时，draggable 助手（helper）要追加到哪一个元素。

支持多个类型：

  • jQuery：一个 jQuery 对象，包含助手（helper）要追加到的元素。
  • Element：要追加助手（helper）的元素。
  • Selector：一个选择器，指定哪一个元素要追加助手（helper）。
  • String：字符串"parent"将促使助手（helper）成为 draggable 的同级。

代码实例：

初始化带有指定appendTo选项的 draggable： 

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

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

// getter
var appendTo = $( ".selector" ).draggable( "option", "appendTo" );
 
// setter
$( ".selector" ).draggable( "option", "appendTo", "body" );
"parent"
axis String 约束在水平轴 (x) 或垂直轴 (y) 上拖拽。可能的值："x","y"。

代码实例：

初始化带有指定axis选项的 draggable： 

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

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

// getter
var axis = $( ".selector" ).draggable( "option", "axis" );
 
// setter
$( ".selector" ).draggable( "option", "axis", "x" );
false
cancel Selector 防止从指定的元素上开始拖拽。

代码实例：

初始化带有指定cancel选项的 draggable： 

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

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

// getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );
 
// setter
$( ".selector" ).draggable( "option", "cancel", ".title" );
"input, textarea, button, select, option"
connectToSortable Selector 允许 draggable 放置在指定的 sortable 上。如果使用了该选项，一个 draggable 可被放置在一个 sortable 列表上，然后成为列表的一部分。注意：helper选项必须设置为"clone"，以便更好地工作。必须包含 可排序小部件（Sortable Widget）。

代码实例：

初始化带有指定connectToSortable选项的 draggable： 

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

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

// getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );
 
// setter
$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );
false
containment Selector 或 Element 或 String 或 Array 约束在指定元素或区域的边界内拖拽。

支持多个类型：

  • Selector：可拖拽元素将被包含在 selector 第一个元素的边界内。如果未找到元素，则不设置 containment。
  • Element：可拖拽元素将被韩寒在元素的边界。
  • String：可能的值："parent"、"document"、"window"。
  • Array：一个数组， 以形式[ x1, y1, x2, y2 ]定义元素的边界。

代码实例：

初始化带有指定containment选项的 draggable： 

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

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

// getter
var containment = $( ".selector" ).draggable( "option", "containment" );
 
// setter
$( ".selector" ).draggable( "option", "containment", "parent" );
false
cursor String 拖拽操作期间的 CSS 光标。

代码实例：

初始化带有指定cursor选项的 draggable： 

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

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

// getter
var cursor = $( ".selector" ).draggable( "option", "cursor" );
 
// setter
$( ".selector" ).draggable( "option", "cursor", "crosshair" );
"auto"
cursorAt Object 设置拖拽助手（helper）相对于鼠标光标的偏移。坐标可通过一个或两个键的组合成一个哈希给出：{ top, left, right, bottom }。

代码实例：

初始化带有指定cursorAt选项的 draggable： 

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

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

// getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );
 
// setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );
false
delay Number 鼠标按下后直到拖拽开始为止的时间，以毫秒计。该选项可以防止点击在某个元素上时不必要的拖拽。

代码实例：

初始化带有指定delay选项的 draggable： 

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

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

// getter
var delay = $( ".selector" ).draggable( "option", "delay" );
 
// setter
$( ".selector" ).draggable( "option", "delay", 300 );
0
disabled Boolean 如果设置为true，则禁用该 draggable。

代码实例：

初始化带有指定disabled选项的 draggable： 

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

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

// getter
var disabled = $( ".selector" ).draggable( "option", "disabled" );
 
// setter
$( ".selector" ).draggable( "option", "disabled", true );
false
distance Number 鼠标按下后拖拽开始前必须移动的距离，以像素计。该选项可以防止点击在某个元素上时不必要的拖拽。

代码实例：

初始化带有指定distance选项的 draggable： 

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

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

// getter
var distance = $( ".selector" ).draggable( "option", "distance" );
 
// setter
$( ".selector" ).draggable( "option", "distance", 10 );
1
grid Array 对齐拖拽助手（helper）到网格，每个 x 和 y 像素。数组形式必须是[ x, y ]。

代码实例：

初始化带有指定grid选项的 draggable： 

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

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

// getter
var grid = $( ".selector" ).draggable( "option", "grid" );
 
// setter
$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );
false
handle Selector 或 Element 如果指定了该选项，则限制开始拖拽，除非鼠标在指定的元素上按下。只有可拖拽（draggable）元素的后代元素才允许被拖拽。

代码实例：

初始化带有指定handle选项的 draggable： 

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

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

// getter
var handle = $( ".selector" ).draggable( "option", "handle" );
 
// setter
$( ".selector" ).draggable( "option", "handle", "h2" );
false
helper String 或 Function() 允许一个 helper 元素用于拖拽显示。

支持多个类型：

  • String：如果设置为"clone"，元素将被克隆，且克隆将被拖拽。
  • Function：一个函数，将返回拖拽时要使用的 DOMElement。

代码实例：

初始化带有指定helper选项的 draggable： 

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

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

// getter
var helper = $( ".selector" ).draggable( "option", "helper" );
 
// setter
$( ".selector" ).draggable( "option", "helper", "clone" );
"original"
iframeFix Boolean 或 Selector 防止拖拽期间 iframes 捕捉鼠标移动（mousemove ）事件。在与cursorAt选项结合使用时，或鼠标光标未覆盖在助手（helper）上时，非常有用。

支持多个类型：

  • Boolean：当设置为true时，透明遮罩将被放置在页面上所有 iframes 上。
  • Selector：匹配 selector 的任意 iframes 将被透明遮罩覆盖。

代码实例：

初始化带有指定iframeFix选项的 draggable： 

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

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

// getter
var iframeFix = $( ".selector" ).draggable( "option", "iframeFix" );
 
// setter
$( ".selector" ).draggable( "option", "iframeFix", true );
false
opacity Number 当被拖拽时助手（helper）的不透明度。

代码实例：

初始化带有指定opacity选项的 draggable： 

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

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

// getter
var opacity = $( ".selector" ).draggable( "option", "opacity" );
 
// setter
$( ".selector" ).draggable( "option", "opacity", 0.35 );
false
refreshPositions Boolean 如果设置为true，在每次鼠标移动（mousemove）时都会计算所有可放置的位置。注意：这解决了高度动态的问题，但是明显降低了性能。

代码实例：

初始化带有指定refreshPositions选项的 draggable： 

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

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

// getter
var refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" );
 
// setter
$( ".selector" ).draggable( "option", "refreshPositions", true );
false
revert Boolean 或 String 或 Function() 当拖拽停止时，元素是否还原到它的开始位置。

支持多个类型：

  • Boolean：如果设置为true，元素总会还原。
  • String：如果设置为"invalid"，还原仅在 draggable 未放置在 droppable 上时发生，如果设置为"valid"则相反。
  • Function：一个函数，确定元素是否还原到它的开始位置。该函数必须返回true才能还原元素。

代码实例：

初始化带有指定revert选项的 draggable： 

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

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

// getter
var revert = $( ".selector" ).draggable( "option", "revert" );
 
// setter
$( ".selector" ).draggable( "option", "revert", true );
false
revertDuration Number 还原（revert）动画的持续时间，以毫秒计。如果revert选项是false则忽略。

代码实例：

初始化带有指定revertDuration选项的 draggable： 

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

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

// getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );
 
// setter
$( ".selector" ).draggable( "option", "revertDuration", 200 );
500
scope String 用于组合配套 draggable 和 droppable 项，除了 droppable 的accept选项之外。一个与 droppable 带有相同的scope值的 draggable 会被该 droppable 接受。

代码实例：

初始化带有指定scope选项的 draggable： 

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

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

// getter
var scope = $( ".selector" ).draggable( "option", "scope" );
 
// setter
$( ".selector" ).draggable( "option", "scope", "tasks" );
"default"
scroll Boolean 如果设置为true，当拖拽时容器会自动滚动。

代码实例：

初始化带有指定scroll选项的 draggable： 

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

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

// getter
var scroll = $( ".selector" ).draggable( "option", "scroll" );
 
// setter
$( ".selector" ).draggable( "option", "scroll", false );
true
scrollSensitivity Number 从要滚动的视区边缘起的距离，以像素计。距离是相对于指针的，不是相对于 draggable。如果scroll选项是false则忽略。

代码实例：

初始化带有指定scrollSensitivity选项的 draggable： 

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

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

// getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );
 
// setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );
20
scrollSpeed Number 当鼠标指针获取到在scrollSensitivity距离内时，窗体滚动的速度。如果scroll选项是false则忽略。

代码实例：

初始化带有指定scrollSpeed选项的 draggable： 

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

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

// getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );
 
// setter
$( ".selector" ).draggable( "option", "scrollSpeed", 100 );
20
snap Boolean 或 Selector 元素是否对齐到其他元素。

支持多个类型：

  • Boolean：当设置为true时，元素会对齐到其它可拖拽（draggable ）元素。
  • Selector：一个选择器，指定要对齐到哪个元素。

代码实例：

初始化带有指定snap选项的 draggable： 

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

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

// getter
var snap = $( ".selector" ).draggable( "option", "snap" );
 
// setter
$( ".selector" ).draggable( "option", "snap", true );
false
snapMode String 决定 draggable 将对齐到对齐元素的哪个边缘。如果snap选项是false则忽略。可能的值："inner"、"outer"、"both"。

代码实例：

初始化带有指定snapMode选项的 draggable： 

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

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

// getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );
 
// setter
$( ".selector" ).draggable( "option", "snapMode", "inner" );
"both"
snapTolerance Number 从要发生对齐的对齐元素边缘起的距离，以像素计。如果snap选项是false则忽略。

代码实例：

初始化带有指定snapTolerance选项的 draggable： 

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

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

// getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );
 
// setter
$( ".selector" ).draggable( "option", "snapTolerance", 30 );
20
stack Selector 控制匹配选择器（selector）的元素集合的 z-index，总是在当前拖拽项的前面，在类似窗口管理器这样的事物中非常有用。

代码实例：

初始化带有指定stack选项的 draggable： 

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

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

// getter
var stack = $( ".selector" ).draggable( "option", "stack" );
 
// setter
$( ".selector" ).draggable( "option", "stack", ".products" );
false
zIndex Number 当被拖拽时，助手（helper）的 Z-index。

代码实例：

初始化带有指定zIndex选项的 draggable： 

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

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

// getter
var zIndex = $( ".selector" ).draggable( "option", "zIndex" );
 
// setter
$( ".selector" ).draggable( "option", "zIndex", 100 );
false

方法 返回 描述
destroy() jQuery (plugin only) 完全移除 draggable 功能。这会把元素返回到它的预初始化状态。
  • 该方法不接受任何参数。

代码实例：

调用 destroy 方法： 

$( ".selector" ).draggable( "destroy" );
disable() jQuery (plugin only) 禁用 draggable。
  • 该方法不接受任何参数。

代码实例：

调用 disable 方法： 

$( ".selector" ).draggable( "disable" );
enable() jQuery (plugin only) 启用 draggable。
  • 该方法不接受任何参数。

代码实例：

调用 enable 方法： 

$( ".selector" ).draggable( "enable" );
option( optionName ) Object 获取当前与指定的optionName关联的值。
  • optionName
    类型：String
    描述：要获取的选项的名称。

代码实例：

调用该方法： 

var isDisabled = $( ".selector" ).draggable( "option", "disabled" );
option() PlainObject 获取一个包含键/值对的对象，键/值对表示当前 draggable 选项哈希。
  • 该方法不接受任何参数。

代码实例：

调用该方法： 

var options = $( ".selector" ).draggable( "option" );
option( optionName, value ) jQuery (plugin only) 设置与指定的optionName关联的 draggable 选项的值。
  • optionName
    类型：String
    描述：要设置的选项的名称。
  • value
    类型：Object
    描述：要为选项设置的值。

代码实例：

调用该方法： 

$( ".selector" ).draggable( "option", "disabled", true );
option( options ) jQuery (plugin only) 为 draggable 设置一个或多个选项。
  • options
    类型：Object
    描述：要设置的 option-value 对。

代码实例：

调用该方法： 

$( ".selector" ).draggable( "option", { disabled: true } );
widget() jQuery 返回一个包含 draggable 元素的jQuery对象。
  • 该方法不接受任何参数。

代码实例：

调用 widget 方法： 

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

事件 类型 描述
create( event, ui ) dragcreate 当 draggable 被创建时触发。
  • event
    类型：Event
  • ui
    类型：Object

注意：ui对象是空的，这里包含它是为了与其他事件保持一致性。

代码实例：

初始化带有指定 create 回调的 draggable： 

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

绑定一个事件监听器到 dragcreate 事件： 

$( ".selector" ).on( "dragcreate", function( event, ui ) {} );
drag( event, ui ) drag 在拖拽期间当鼠标移动时触发。
  • event
    类型：Event
  • ui
    类型：Object
    • helper
      类型：jQuery
      描述：jQuery 对象，表示被拖拽的助手（helper）。
    • position
      类型：Object
      描述：助手（helper）的当前 CSS 位置，比如{ top, left }对象。
    • offset
      类型：Object
      描述：助手（helper）的当前偏移位置，比如{ top, left }对象。

代码实例：

初始化带有指定 drag 回调的 draggable： 

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

绑定一个事件监听器到 drag 事件： 

$( ".selector" ).on( "drag", function( event, ui ) {} );
start( event, ui ) dragstart 当拖拽开始时触发。
  • event
    类型：Event
  • ui
    类型：Object
    • helper
      类型：jQuery
      描述：jQuery 对象，表示被拖拽的助手（helper）。
    • position
      类型：Object
      描述：助手（helper）的当前 CSS 位置，比如{ top, left }对象。
    • offset
      类型：Object
      描述：助手（helper）的当前偏移位置，比如{ top, left }对象。

代码实例：

初始化带有指定 start 回调的 draggable： 

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

绑定一个事件监听器到 dragstart 事件： 

$( ".selector" ).on( "dragstart", function( event, ui ) {} );
stop( event, ui ) dragstop 当拖拽停止时触发。
  • event
    类型：Event
  • ui
    类型：Object
    • helper
      类型：jQuery
      描述：jQuery 对象，表示被拖拽的助手（helper）。
    • position
      类型：Object
      描述：助手（helper）的当前 CSS 位置，比如{ top, left }对象。
    • offset
      类型：Object
      描述：助手（helper）的当前偏移位置，比如{ top, left }对象。

代码实例：

初始化带有指定 stop 回调的 draggable： 

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

绑定一个事件监听器到 dragstop 事件： 

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

实例

一个简单的 jQuery UI 可拖拽小部件（Draggable Widget）。 

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>可拖拽小部件（Draggable 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;
  }
  </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="draggable">请拖拽我！</div>
 
<script>
$( "#draggable" ).draggable();
</script>
 
</body>
</html>
上一篇
© 2021 jiaocheng.bubufx.com  联系我们
ICP备案：鲁ICP备09046678号-3