多应用+插件架构,代码干净,二开方便,首家独创一键云编译技术,文档视频完善,免费商用码云13.8K 广告
# jQuery UI API - 可拖拽小部件(Draggable Widget) ## 所属类别 [交互(Interactions)](ref-interactions.html) ## 用法 **描述:**允许使用鼠标移动元素。 **版本新增:**1.0 **依赖:** * [UI 核心(UI Core)](ref-ui-core.html) * [部件库(Widget Factory)](api-jQuery-widget.html) * [鼠标交互(Mouse Interaction)](api-mouse.html) **注释:**让被选元素可被鼠标拖拽。如果您不只是拖拽,而是拖拽 & 放置,请查看 [jQuery UI 可放置(Droppable)插件](api-droppable.html),为可拖拽元素提供了一个放置目标。 ### 快速导航 | 选项 | 方法 | 事件 | | --- | --- | --- | | [addClasses](#option-addClasses)[appendTo](#option-appendTo)[axis](#option-axis)[cancel](#option-cancel)[connectToSortable](#option-connectToSortable)[containment](#option-containment)[cursor](#option-cursor)[cursorAt](#option-cursorAt)[delay](#option-delay)[disabled](#option-disabled)[distance](#option-distance)[grid](#option-grid)[handle](#option-handle)[helper](#option-helper)[iframeFix](#option-iframeFix)[opacity](#option-opacity)[refreshPositions](#option-refreshPositions)[revert](#option-revert)[revertDuration](#option-revertDuration)[scope](#option-scope)[scroll](#option-scroll)[scrollSensitivity](#option-scrollSensitivity)[scrollSpeed](#option-scrollSpeed)[snap](#option-snap)[snapMode](#option-snapMode)[snapTolerance](#option-snapTolerance)[stack](#option-stack)[zIndex](#option-zIndex) | [destroy](#method-destroy)[disable](#method-disable)[enable](#method-enable)[option](#method-option)[widget](#method-widget) | [create](#event-create)[drag](#event-drag)[start](#event-start)[stop](#event-stop) | #### addClasses **类型**:Boolean **描述**:如果设置为 `false`,将阻止 `ui-draggable` class 被添加。当在数百个元素上调用 `.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)](api-sortable.html)。 **代码实例:** 初始化带有指定 `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> ```