185 lines
6.7 KiB
Markdown
185 lines
6.7 KiB
Markdown
# v-drag
|
||
|
||
## 简介
|
||
|
||
`v-drag` 指令用于处理根据鼠标拖拽来变换目标元素形态、位置等的场景。
|
||
|
||
## 示例
|
||
|
||
拖动元素。
|
||
|
||
[[ demo src="/demo/directives/drag/base.vue" ]]
|
||
|
||
在指定元素区域内拖动。
|
||
|
||
[[ demo src="/demo/directives/drag/containment.vue" ]]
|
||
|
||
拖动多个元素。
|
||
|
||
[[ demo src="/demo/directives/drag/targets.vue" ]]
|
||
|
||
限制拖动方向。
|
||
|
||
[[ demo src="/demo/directives/drag/axis.vue" ]]
|
||
|
||
水平排序。
|
||
|
||
[[ demo src="/demo/directives/drag/sort-x.vue" ]]
|
||
|
||
垂直排序。
|
||
|
||
[[ demo src="/demo/directives/drag/sort-y.vue" ]]
|
||
|
||
## API
|
||
|
||
:::tip
|
||
指令的具体用法请参考[官方文档](https://cn.vuejs.org/v2/guide/syntax.html#%E6%8C%87%E4%BB%A4)。更多详细参数请参考[自定义指令](https://cn.vuejs.org/v2/guide/custom-directive.html#%E9%92%A9%E5%AD%90%E5%87%BD%E6%95%B0%E5%8F%82%E6%95%B0)。
|
||
:::
|
||
|
||
### 绑定值
|
||
|
||
类型：`Object`。
|
||
|
||
| 参数 | 类型 | 默认值 | 描述 |
|
||
| -- | -- | -- | -- |
|
||
| `targets` | `Array<string|Vue|HTMLElement>` | `[]` | [^targets] |
|
||
| `type` | `string` | - | 该参数指定变化的类型，目前内置了 `translate` 类型（变换目标元素位置），可以进行[扩展](#扩展)。 |
|
||
| `draggable` | `boolean` | `true` | 是否响应鼠标拖拽操作。 |
|
||
| `containment` | `string|Vue|HTMLElement|Object` | - | [^containment] |
|
||
| `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`](https://developer.mozilla.org/zh-CN/docs/Web/API/DragEvent) | 原生拖拽事件对象。 |
|
||
| `distanceX` | `number` | 水平方向自拖拽开始以后移动的总距离。 |
|
||
| `distanceY` | `number` | 垂直方向自拖拽开始以后移动的总距离。 |
|
||
+++
|
||
^^^
|
||
|
||
^^^targets
|
||
该参数指定了目标元素集合，在指令所在元素上拖拽鼠标的时候，会按照指定的方式变换所有目标元素。
|
||
|
||
+++类型详情
|
||
| 类型 | 描述 |
|
||
| -- | -- |
|
||
| `string` | 在指令所在组件上下文中，根据 `ref` 查找指定的 DOM 元素集合。 |
|
||
| `Vue` | 组件实例，直接使用 `vm.$el` 元素。 |
|
||
| `HTMLElement` | DOM 元素，直接使用。 |
|
||
+++
|
||
^^^
|
||
|
||
^^^containment
|
||
目标元素在变换的时候，应当始终位于 `containment` 所指定的区域内。
|
||
|
||
如果通过 `containment` 解析出来是一个 DOM 元素，那么所有目标元素就应当在该元素内变换；如果解析出来是一个矩形区域描述（相对于视口的 top、left、width、height），那么所有目标元素就应当在该矩形区域内变换。
|
||
|
||
+++类型详情
|
||
| 类型 | 描述 |
|
||
| -- | -- |
|
||
| `string` | 如果以 `@` 开头（可以通过[全局配置](../advanced/global-config) `drag.prefix` 修改），就被认为是特殊逻辑，会透传给具体的 Handler 处理；否则，在指令所在组件上下文中，根据 `ref` 查找指定的 DOM 元素。 |
|
||
| `Vue` | 根据组件实例找到 DOM 元素。 |
|
||
| `HTMLElement` | 直接接收 DOM 元素。 |
|
||
| `Object` | 接受任意包含 `{top, left, width, height}` 字段的普通对象，表示相对于视口的矩形区域的坐标和尺寸，四个字段均为 `number` 类型。 |
|
||
+++
|
||
^^^
|
||
|
||
### 修饰符
|
||
|
||
对应 `Object` 绑定值中的 `type`/`axis`。例如：
|
||
|
||
```html
|
||
<!-- 沿着垂直方向做位移变换 -->
|
||
<div v-drag.translate.y></div>
|
||
```
|
||
|
||
### 参数
|
||
|
||
对应 `Object` 绑定值中的 `targets`。值是一个用 `,` 分隔的、表示一到多个 `ref` 的字符串。例如：
|
||
|
||
```html
|
||
<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|Object` | - | 参见上面的基础描述 |
|
||
| `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` 指令：
|
||
|
||
```js
|
||
import BaseHandler from 'veui/directives/drag/BaseHandler'
|
||
import { registerHandler } from 'veui/directives/drag'
|
||
|
||
class RotateHandler extends BaseHandler { }
|
||
|
||
registerHandler('rotate', RotateHandler)
|
||
```
|
||
|
||
然后通过 `type` 参数使用 `RotateHandler`：
|
||
|
||
```html
|
||
<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()` | 重置变换。 |
|