Draggable Widget

Categories: Interactions

version added: 1.0

Description: 该组件可以让你使用鼠标拖动所有元素。

QuickNavExamples

让被选择元素可以被鼠标拖动。如果你想把元素拖放到另一个元素内部，查看jQuery UI Droppable plugin,该组件为被拖动元素提供了一个目标容器。

Dependencies（依赖性）

Options

addClassesType: Boolean

Default: true如果值设置为false, ui-draggable样式类将不能被添加引用。当在大量元素上调用.draggable()时，你可能会想要这样设置，作为一个性能优化。Code examples:

使用addClasses选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置addClasses选项

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

// setter
$( ".selector" ).draggable( "option", "addClasses", false );

appendToType: jQuery or Element or Selector or String

Default: "parent"当进行拖动时，拖动组件助手应该被添加到的元素。支持多种类型:

jQuery: 一个含有要被添加拖动组件助手的元素的Jquery对象。
Element: 要被添加拖动组件助手的元素。
Selector: 一个用来识别要被添加拖动组件助手的元素的选择器。
String: 字符串"parent"将会使拖动组件助手成为组件的同级元素。

Code examples:

使用appendTo选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置appendTo选项

// getter
var appendTo = $( ".selector" ).draggable( "option", "appendTo" );

// setter
$( ".selector" ).draggable( "option", "appendTo", "body" );

axisType: String

Default: false约束拖动的动作只能在水平(x轴)或垂直(y轴)上执行。可选值: "x", "y"。Code examples:

使用axis选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置axis选项：

// getter
var axis = $( ".selector" ).draggable( "option", "axis" );

// setter
$( ".selector" ).draggable( "option", "axis", "x" );

cancelType: Selector

Default: "input,textarea,button,select,option"防止在指定元素上开始拖动。Code examples:

使用cancel选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置cancel选项：

// getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );

// setter
$( ".selector" ).draggable( "option", "cancel", ".title" );

connectToSortableType: Selector

Default: false允许draggable被拖拽到指定的sortables中。如果使用了该选项，被拖动的元素可以被放置于一个应用了排序组件的元素列表中并成为该列表的一部分。注意: 为了完美的使用该特性，helper选项必须被设置为"clone"。必须包含jQuery UI 排序组件。Code examples:

使用connectToSortable选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置connectToSortable选项：

// getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );

// setter
$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );

containmentType: Selector or Element or String or Array

Default: false可以限制draggable只能在指定的元素或区域的边界以内进行拖动。支持多种类型:

Selector: 可拖动元素将被置于由选择器指定的第一个元素的起界限作用的盒模型中。如果没有找到任何元素，则不会设置界限。
Element: 可拖动的元素将包含该元素的边界框。
String:可选值: "parent", "document", "window".
Array: 以 [ x1, y1, x2, y2 ] 数组形式定义一个限制区域.

Code examples:

使用containment选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置containment选项：

// getter
var containment = $( ".selector" ).draggable( "option", "containment" );

// setter
$( ".selector" ).draggable( "option", "containment", "parent" );

cursorType: String

Default: "auto"指定在做拖拽动作时，鼠标的CSS样式。Code examples:

使用cursor选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置cursor选项：

// getter
var cursor = $( ".selector" ).draggable( "option", "cursor" );

// setter
$( ".selector" ).draggable( "option", "cursor", "crosshair" );

cursorAtType: Object

Default: false设置拖动帮手相对于鼠标光标的偏移量。坐标可被指定为一个散列使用的组合中的一个或两个键：{ top, left, right, bottom } 。Code examples:

使用cursorAt选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置cursorAt选项：

// getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );

// setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );

delayType: Number

Default: 0当鼠标按下后，指定时延迟间后才开始激活拖拽动作（单位：毫秒）。此选项可用来阻止当点击一个元素时可能发生的非期望拖动行为。Code examples:

使用delay选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置delay选项：

// getter
var delay = $( ".selector" ).draggable( "option", "delay" );

// setter
$( ".selector" ).draggable( "option", "delay", 300 );

disabledType: Boolean

Default: false如果该值设置为true，拖动特效将被禁用。Code examples:

使用disabled选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置disabled选项：

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

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

distanceType: Number

Default: 1当鼠标点下后，只有移动指定像素后才开始激活拖拽动作，单位为像素。此选项可用来阻止当点击一个元素时可能发生的非期望拖动行为。Code examples:

使用distance选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置distance选项：

// getter
var distance = $( ".selector" ).draggable( "option", "distance" );

// setter
$( ".selector" ).draggable( "option", "distance", 10 );

gridType: Array

Default: false拖拽元素时，只能以指定大小的方格进行拖动。数组形式为[ x, y ]。Code examples:

使用grid选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置grid 选项:

// getter
var grid = $( ".selector" ).draggable( "option", "grid" );

// setter
$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );

handleType: Selector or Element

Default: false当参数值为true时,只有在特定的元素上触发鼠标按下事件时，才可以拖动。只有被拖到元素的子元素才可以应用该参数。Code examples:

使用handle选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置handle 选项:

// getter
var handle = $( ".selector" ).draggable( "option", "handle" );

// setter
$( ".selector" ).draggable( "option", "handle", "h2" );

helperType: String or Function()

Default: "original"允许一个元素被用来进行拖动。支持多种类型:

String:如果值设置为"clone", 那么该元素将会被复制，并且被复制的元素将被拖动。
Function: 当拖动时，函数将返回一个DOM元素以供使用。

Code examples:

使用helper选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置helper 选项:

// getter
var helper = $( ".selector" ).draggable( "option", "helper" );

// setter
$( ".selector" ).draggable( "option", "helper", "clone" );

iframeFixType: Boolean or Selector

Default: false在拖动期间阻止iframe捕捉鼠标移过事件。与cursorAt选项搭配使用时或者当鼠标指针可能不在拖动助手元素之上时，该参数非常有用。支持多种类型:

Boolean: 当设置为true, 透明层将被放置于页面上的所有iframe之上。/li>
Selector: 任何由选择器匹配的iframe将被透明层覆盖。

Code examples:

使用iframeFix选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置iframeFix 选项:

// getter
var iframeFix = $( ".selector" ).draggable( "option", "iframeFix" );

// setter
$( ".selector" ).draggable( "option", "iframeFix", true );

opacityType: Number

Default: false当拖动时，拖动助手元素的不透明度。Code examples:

使用opacity选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置opacity 选项:

// getter
var opacity = $( ".selector" ).draggable( "option", "opacity" );

// setter
$( ".selector" ).draggable( "option", "opacity", 0.35 );

refreshPositionsType: Boolean

Default: false如果设置为true，所有的可拖动位置在每次鼠标移动时都会被计算。 注意: 这解决了具有高度动态内容页面的问题，但是却降低了性能。Code examples:

使用refreshPositions选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置refreshPositions 选项:

// getter
var refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" );

// setter
$( ".selector" ).draggable( "option", "refreshPositions", true );

revertType: Boolean or String

Default: false当拖动停止时，元素是否要被重置到它的初始位置。支持多种类型:

Boolean: 如果设置为true，当拖动停止时，元素位置将被重置。
String: 如果设置为"invalid", 重置仅当拖动没有被放置于一个可放置的对象时才会发生。如果设置为"valid", 情况则相反。

Code examples:

使用revert选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置revert 选项:

// getter
var revert = $( ".selector" ).draggable( "option", "revert" );

// setter
$( ".selector" ).draggable( "option", "revert", true );

revertDurationType: Number

Default: 500动画重置时间, 单位为微秒。如果revert选项设置为false，则忽略（译者注：即被拖到元素不会被重置。）。Code examples:

使用revertDuration选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置revertDuration 选项:

// getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );

// setter
$( ".selector" ).draggable( "option", "revertDuration", 200 );

scopeType: String

Default: "default"被用来将拖动组件和拖动至容器组件的参数进行分组, 除了拖动至容器组件的accept选项。如果一个一般拖动组件的scope参数值和一个拖动至容器组件的scope参数值一样，那么这个一般拖动组件将被接受为拖动至容器组件。Code examples:

使用scope选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置scope 选项:

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

// setter
$( ".selector" ).draggable( "option", "scope", "tasks" );

scrollType: Boolean

Default: true如果设置为true, 当拖动时，div盒模型将自动翻滚。Code examples:

使用scroll选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置scroll 选项:

// getter
var scroll = $( ".selector" ).draggable( "option", "scroll" );

// setter
$( ".selector" ).draggable( "option", "scroll", false );

scrollSensitivityType: Number

Default: 20离开可视区域边缘多少距离开始滚动。距离是相对指针进行计算的，而不是被拖到元素本身。如果scroll 选项设置为false，则不滚动。Code examples:

使用scrollSensitivity选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置scrollSensitivity 选项:

// getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );

// setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );

scrollSpeedType: Number

Default: 20当鼠标指针的值小于scrollSensitivity的值时，窗口滚动的速度。如果scroll选项设置为false，则该参数无效。Code examples:

使用scrollSpeed选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置scrollSpeed 选项:

// getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );

// setter
$( ".selector" ).draggable( "option", "scrollSpeed", 100 );

snapType: Boolean or Selector

Default: false决定一个元素是否应该吸附到其它元素上。支持多种类型:

Boolean: 当设置为 true时, 元素将可以吸附到所有其它可拖动元素上。
Selector: 确定被吸附元素。

Code examples:

使用snap选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置snap 选项:

// getter
var snap = $( ".selector" ).draggable( "option", "snap" );

// setter
$( ".selector" ).draggable( "option", "snap", true );

snapModeType: String

Default: "both"决定可拖动元素将要吸附到哪个元素的边缘。如果snap选项设置为false，则忽略该参数。可选值: "inner", "outer", "both".Code examples:

使用snapMode选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置snapMode 选项:

// getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );

// setter
$( ".selector" ).draggable( "option", "snapMode", "inner" );

snapToleranceType: Number

Default: 20当距离可吸附元素多远时，触发吸附事件。如果snap选项设置为false，则忽略该参数。Code examples:

使用snapTolerance选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置snapTolerance 选项:

// getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );

// setter
$( ".selector" ).draggable( "option", "snapTolerance", 30 );

stackType: Selector

Default: false控制由选择器所触发的一系列元素的z-index值, 总是将当前被拖动对象至于最前。对于像窗口管理这样的应用来说，非常有用。Code examples:

使用stack选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置stack 选项:

// getter
var stack = $( ".selector" ).draggable( "option", "stack" );

// setter
$( ".selector" ).draggable( "option", "stack", ".products" );

zIndexType: Number

Default: false当被拖动时，拖动助手的Z-index值。Code examples:

使用zIndex选项初始化Draggable Widget：

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

在组件初始化之后，读取或设置zIndex 选项:

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

// setter
$( ".selector" ).draggable( "option", "zIndex", 100 );

Methods

destroy()

完全销毁一般拖动组件的功能，这将使元素返回它的初始状态。

这个方法不接受任何参数。

Code examples:

请求destroy方法:

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

disable()

禁用一般拖动组件。

这个方法不接受任何参数。

Code examples:

请求disable方法:

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

enable()

启用一般拖动组件。

这个方法不接受任何参数。

Code examples:

请求enable方法:

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

option( optionName )Returns: Object

获取与optionName对应的参数值。

optionNameType: String要获取的值所对应的选项的名称。

Code examples:

请求方法:

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

option()Returns: PlainObject

获取一个包含有描述当前一般拖动组件选项哈希值的键/值对。

这个方法不接受任何参数。

Code examples:

请求方法:

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

option( optionName, value )

设置一般拖动组件选项的值，选项名称由optionName指定。

optionNameType: String要设置的选项的名称。
valueType: Object要为选项设置的参数值。

Code examples:

请求方法:

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

option( options )

为一般拖动组件设置一个或多个选项值。

optionsType: Object要设置的选项与值之间的映射关系。

Code examples:

请求方法:

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

widget()Returns: jQuery

返回一个包含有可拖动元素的jQuery对象。

这个方法不接受任何参数。

Code examples:

请求widget方法:

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

Events

create( event, ui )Type: `dragcreate`

当一般拖动组件被创建时触发。

eventType: Event
uiType: Object

注意: ui对象是空的，但是为了与其它元素保持一直，它总是被包含。

Code examples:

使用create回调函数指定事件:

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

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

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

drag( event, ui )Type: `drag`

当鼠标在拖动过程中移动时触发。

eventType: Event
uiType: Object
- helperType: jQuery代表被拖动的元素。
- positionType: Object当前元素的CSS位置，以{ top, left }形式给出。
- offsetType: Object当前元素的偏移位置，以{ top, left }形式给出。

Code examples:

使用drag回调函数指定事件:

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

绑定一个事件监听者到drag事件:

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

start( event, ui )Type: `dragstart`

当拖动开始时触发。

eventType: Event
uiType: Object
- helperType: jQuery代表被拖动的元素。
- positionType: Object当前元素的CSS位置，以{ top, left }形式给出。
- offsetType: Object当前元素的偏移位置，以{ top, left }形式给出。

Code examples:

使用start callback specified:

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

拖动事件绑定一个事件监听器：

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

stop( event, ui )Type: `dragstop`

当拖动停止时触发。

eventType: Event
uiType: Object
- helperType: jQuery代表被拖动的元素。
- positionType: Object当前元素的CSS位置，以{ top, left }形式给出。
- offsetType: Object当前元素的偏移位置，以{ top, left }形式给出。

Code examples:

使用start回调函数指定事件:

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

绑定一个事件监听者到dragstart事件:

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

Example:

一个简单的jQuery UI一般拖动

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>draggable demo</title>
  <link rel="stylesheet" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css">
  <style>
  #draggable {
    width: 100px;
    height: 100px;
    background: #ccc;
  }
  </style>
  <script src="http://code.jquery.com/jquery-1.9.1.js"></script>
  <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.js"></script>
</head>
<body>

<div id="draggable">Drag me</div>

<script>
$( "#draggable" ).draggable();
</script>

</body>
</html>

version added: 1.0

QuickNavExamples

Options

Methods

Events

Dependencies（依赖性）

Options

addClassesType: Boolean

appendToType: jQuery or Element or Selector or String

axisType: String

cancelType: Selector

connectToSortableType: Selector

containmentType: Selector or Element or String or Array

cursorType: String

cursorAtType: Object

delayType: Number

disabledType: Boolean

distanceType: Number

gridType: Array

handleType: Selector or Element

helperType: String or Function()

iframeFixType: Boolean or Selector

opacityType: Number

refreshPositionsType: Boolean

revertType: Boolean or String

revertDurationType: Number

scopeType: String

scrollType: Boolean

scrollSensitivityType: Number

scrollSpeedType: Number

snapType: Boolean or Selector

snapModeType: String

snapToleranceType: Number

stackType: Selector

zIndexType: Number

Methods

destroy()

disable()

enable()

option( optionName )Returns: Object

option()Returns: PlainObject

option( optionName, value )

option( options )

widget()Returns: jQuery

Events

create( event, ui )Type: dragcreate

drag( event, ui )Type: drag

start( event, ui )Type: dragstart

stop( event, ui )Type: dragstop

Example:

一个简单的jQuery UI一般拖动

create( event, ui )Type: `dragcreate`

drag( event, ui )Type: `drag`

start( event, ui )Type: `dragstart`

stop( event, ui )Type: `dragstop`