docs_vue2/one/docs/directives/v-drag.md

v-drag

简介

v-drag 指令用于处理根据鼠标拖拽来变换目标元素形态、位置等的场景。

示例

拖动元素。

在指定元素区域内拖动。

拖动多个元素。

限制拖动方向。

水平排序。

垂直排序。

API

:::tip 指令的具体用法请参考官方文档。更多详细参数请参考自定义指令。 :::

绑定值

类型：Object。

参数	类型	默认值	描述
targets	`Array<string	Vue	HTMLElement>`
type	string	-	该参数指定变化的类型，目前内置了 translate 类型（变换目标元素位置），可以进行扩展。
draggable	boolean	true	是否响应鼠标拖拽操作。
containment	`string	Vue	HTMLElement
axis	string	-	限制所有目标元素只能在水平或者垂直方向上做变换。取值为：x、y。
dragstart	function(): Object	function() {}	[^dragstart]
drag	function(): Object	function() {}	[^drag]
disabled	boolean	false	该指令是否被禁用。
dragend	function(): Object	function() {}	鼠标拖拽结束事件的回调函数。回调参数同 drag。
ready	function	function() {}	指令初始化完成的回调函数，会传出一个句柄对象参数，该对象上有一个 reset() 方法，用于将所有目标元素重置为变换之前的样子。

:::warning Object 类型提供的参数会覆盖通过指令参数、修饰符指定的参数。 :::

^^^dragstart 鼠标拖拽开始事件的回调函数。回调参数为 ({ event: DragEvent })。 ^^^

^^^drag 鼠标拖拽中事件的回调函数。回调参数为 ({ event, distanceX, distanceY })。

+++参数详情

参数	类型	描述
event	DragEvent	原生拖拽事件对象。
distanceX	number	水平方向自拖拽开始以后移动的总距离。
distanceY	number	垂直方向自拖拽开始以后移动的总距离。
+++
^^^

^^^targets 该参数指定了目标元素集合，在指令所在元素上拖拽鼠标的时候，会按照指定的方式变换所有目标元素。

+++类型详情

类型	描述
string	在指令所在组件上下文中，根据 ref 查找指定的 DOM 元素集合。
Vue	组件实例，直接使用 vm.$el 元素。
HTMLElement	DOM 元素，直接使用。
+++
^^^

^^^containment 目标元素在变换的时候，应当始终位于 containment 所指定的区域内。

如果通过 containment 解析出来是一个 DOM 元素，那么所有目标元素就应当在该元素内变换；如果解析出来是一个矩形区域描述（相对于视口的 top、left、width、height），那么所有目标元素就应当在该矩形区域内变换。

+++类型详情

类型	描述
string	如果以 @ 开头（可以通过全局配置 drag.prefix 修改），就被认为是特殊逻辑，会透传给具体的 Handler 处理；否则，在指令所在组件上下文中，根据 ref 查找指定的 DOM 元素。
Vue	根据组件实例找到 DOM 元素。
HTMLElement	直接接收 DOM 元素。
Object	接受任意包含 {top, left, width, height} 字段的普通对象，表示相对于视口的矩形区域的坐标和尺寸，四个字段均为 number 类型。
+++
^^^

修饰符

对应 Object 绑定值中的 type/axis。例如：

<!-- 沿着垂直方向做位移变换 -->
<div v-drag.translate.y></div>

参数

对应 Object 绑定值中的 targets。值是一个用 , 分隔的、表示一到多个 ref 的字符串。例如：

<div v-drag:box1,box2></div>

拖拽排序（v-drag.sort）

可以通过 v-drag.sort 或 v-drag="{type: 'sort', ...}" 来实现拖拽排序。

绑定值

类型：Object。

参数	类型	默认值	描述
name	string	-	用来标记一组项目，在这组项目中进行排序。
type	string	-	该参数指定变化的类型，拖拽排序是 sort 。
containment	`string	Vue	HTMLElement
axis	string	-	限制所有目标元素只能在水平或者垂直方向上做排序。取值为：x、y。
callback	function(toIndex: number, fromIndex: number): void	-	[^sort_callback]
debug	boolean	false	在开发模式（process.env.NODE_ENV === 'development'）下在 DOM 上显示热区标记以方便调试。

^^^sort_callback 排序指令仅仅通过该回调告诉用户排序的情况，即：从原来位置（fromIndex）移动到新位置（toIndex）,用户自己应该在该回调中对数据源进行调整位置。

** 回调触发时机：当 fromIndex 元素的中心点拖动到热区（toIndex 元素尾部和 toIndex+1 元素首部之间的区域）中触发。**

^^^

扩展

可以通过继承 BaseHandler 扩展 v-drag 指令：

import BaseHandler from 'veui/directives/drag/BaseHandler'
import { registerHandler } from 'veui/directives/drag'

class RotateHandler extends BaseHandler { }

registerHandler('rotate', RotateHandler)

然后通过 type 参数使用 RotateHandler：

<div v-drag="{ type: 'rotate' }"></div>
<!-- 或者 -->
<div v-drag.rotate></div>

:::warning type 的名称不能与已有的修饰符冲突。 :::

BaseHandler

BaseHandler 中各成员的说明如下：

成员名	类型	描述
options	Object	解析出来的参数组成的对象。
context	Vue	指令所在的组件。
isDragging	boolean	是否处于拖拽过程中。
start	function(Object)	同绑定值中的 dragstart 字段。
drag	function(Object)	同绑定值中的 drag 字段。
end	function(Object)	同绑定值中的 dragend 字段。
destroy	function()	指令与 DOM 元素解绑的时候调用。
setOptions	function(options)	设置参数。
reset	function()	重置变换。