151 lines
5.3 KiB
Markdown
151 lines
5.3 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" ]]
|
|||
|
|
|
|||
|
|
## 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] |
|
|||
|
|
| `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>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 扩展
|
|||
|
|
|
|||
|
|
可以通过继承 `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()` | 重置变换。 |
|