feat: publicize doc implemetation
This commit is contained in:
Justineo
150
one/docs/directives/v-drag.md
Normal file
150
one/docs/directives/v-drag.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# 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()` | 重置变换。 |
|
||||
60
one/docs/directives/v-longpress.md
Normal file
60
one/docs/directives/v-longpress.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# v-longpress
|
||||
|
||||
## 简介
|
||||
|
||||
`v-longpress` 指令用于处理鼠标长按事件。
|
||||
|
||||
## 示例
|
||||
|
||||
## 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)。
|
||||
:::
|
||||
|
||||
### 绑定值
|
||||
|
||||
类型：`function|Object`。
|
||||
|
||||
使用 `function` 类型则绑定值表示触发长按或后续重复触发的回调函数。例如：
|
||||
|
||||
```html
|
||||
<button v-longpress="handleLongPress">+</button>
|
||||
```
|
||||
|
||||
使用 `Object` 类型时绑定值可完整配置所有参数。例如：
|
||||
|
||||
```html
|
||||
<button v-longpress="{
|
||||
timeout: 500,
|
||||
handler: handleLongPress,
|
||||
repeat: true,
|
||||
repeatInterval: 100
|
||||
}">+</button>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 描述 |
|
||||
| -- | -- | -- | -- |
|
||||
| `timeout` | `number` | `longpress.timeout` | 触发长按等待的毫秒数。可进行[全局配置](#全局配置)。 |
|
||||
| `handler` | `function` | `function() {}` | 触发长按及后续重复触发时的回调函数。 |
|
||||
| `repeat` | `boolean` | `false` | 保持长按时是否重复触发回调，类似按下键盘按键后连续自动输入的效果。 |
|
||||
| `repeatInterval` | `number` | `longpress.repeatInterval` | 重复触发回调间隔的毫秒数。可进行[全局配置](#全局配置)。 |
|
||||
|
||||
:::warning
|
||||
`Object` 类型提供的参数会覆盖通过指令参数、修饰符指定的参数。
|
||||
:::
|
||||
|
||||
### 修饰符
|
||||
|
||||
对应 `Object` 类型绑定值中的 `repeat`。例如：
|
||||
|
||||
```html
|
||||
<button v-longpress.repeat="increase">+</button>
|
||||
```
|
||||
|
||||
### 全局配置
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
| -- | -- | -- | -- |
|
||||
| `longpress.timeout` | `number` | `500` | 触发长按等待的毫秒数。 |
|
||||
| `longpress.repeatInterval` | `number` | `100` | 重复触发回调间隔的毫秒数。 |
|
||||
81
one/docs/directives/v-nudge.md
Normal file
81
one/docs/directives/v-nudge.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# v-nudge
|
||||
|
||||
## 简介
|
||||
|
||||
`v-nudge` 指令用于使用键盘方向键对值进行调整。
|
||||
|
||||
:::warning
|
||||
应用 `v-nudge` 的元素或组件根元素必须可以接收焦点。可以使用本身就会接收焦点的元素如 `<button>`、`<input>` 或者使用 [`tabindex` 属性](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Global_attributes/tabindex)。
|
||||
:::
|
||||
|
||||
## 示例
|
||||
|
||||
:::tip
|
||||
按方向键时如果同时按下了 <kbd>shift</kbd> 或 <kbd>alt</kbd> 键，则变化值会被放大 10 倍或缩小 10 倍。
|
||||
:::
|
||||
|
||||
[[ demo src="/demo/directives/nudge.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)。
|
||||
:::
|
||||
|
||||
### 绑定值
|
||||
|
||||
类型：`function|Object`。
|
||||
|
||||
使用 `function` 类型则绑定值表示按下方向键后触发的回调函数。例如：
|
||||
|
||||
```html
|
||||
<div tabindex="-1" v-nudge="update"></div>
|
||||
```
|
||||
|
||||
使用 `Object` 类型时绑定值可完整配置所有参数。例如：
|
||||
|
||||
```html
|
||||
<div tabindex="-1" v-nudge="{
|
||||
step: 5,
|
||||
axis: 'y',
|
||||
update: increase
|
||||
}"></div>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 描述 |
|
||||
| -- | -- | -- | -- |
|
||||
| `axis` | `string` | `y` | 限制只能使用左右或上下方向键调整。取值为：`x`、`y`。 |
|
||||
| `step` | `number` | `nudge.step` | 步进值。可进行[全局配置](#全局配置)。 |
|
||||
| `update` | `function(delta: number)` | `function() {}` | 值发生变化时触发，传入变化值。参数 `delta` 为计算后的数值变化量。 |
|
||||
|
||||
:::warning
|
||||
`Object` 类型提供的参数会覆盖通过指令参数、修饰符指定的参数。
|
||||
:::
|
||||
|
||||
:::warning
|
||||
`v-nudge` 只生成按方向键得到的变化值，本身并不会对值进行修改，需要使用者在 `update` 回调中自行处理。
|
||||
:::
|
||||
|
||||
### 修饰符
|
||||
|
||||
对应 `Object` 类型绑定值中的 `axis`/`step`。例如：
|
||||
|
||||
```html
|
||||
<div tabindex="-1" v-nudge.x.2="{ update: delta => this.val += delta }"></div>
|
||||
```
|
||||
|
||||
| 值 | 描述 |
|
||||
| -- | -- |
|
||||
| `x` | 限制只能使用左右方向键调整。 |
|
||||
| `y` | 限制只能使用上下方向键调整。 |
|
||||
| <var>step</var> | 步进值，注意这里 <var>step</var> 是一个变量。 |
|
||||
|
||||
:::warning
|
||||
在修饰符中的唯一正整数将被识别为 `step`。
|
||||
:::
|
||||
|
||||
### 全局配置
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
| -- | -- | -- | -- |
|
||||
| `nudge.step` | `number` | `1` | 步进值。 |
|
||||
91
one/docs/directives/v-outside.md
Normal file
91
one/docs/directives/v-outside.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# v-outside
|
||||
|
||||
## 简介
|
||||
|
||||
`v-outside` 指令用于检测是否在某些元素之外触发了指定的事件，比如判断鼠标是否点击了元素 A 和 B 范围之外的元素。
|
||||
|
||||
## 示例
|
||||
|
||||
监测外部点击事件。
|
||||
|
||||
[[ demo src="/demo/directives/outside/click.vue" ]]
|
||||
|
||||
监测鼠标移出事件。
|
||||
|
||||
[[ demo src="/demo/directives/outside/hover.vue" ]]
|
||||
|
||||
如果鼠标在指定时间内，没有移回目标元素区域，就触发外部事件回调函数。
|
||||
|
||||
[[ demo src="/demo/directives/outside/hover-with-delay.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)。
|
||||
:::
|
||||
|
||||
### 绑定值
|
||||
|
||||
类型：`function|Object`。
|
||||
|
||||
通过 `function` 类型配置触发外部事件时的回调函数。例如：
|
||||
|
||||
```html
|
||||
<div v-outside="handler"></div>
|
||||
```
|
||||
|
||||
使用 `Object` 类型时绑定值可完整配置所有参数。例如：
|
||||
|
||||
```html
|
||||
<div v-resize="{
|
||||
refs: 'box1,box2'
|
||||
handler: handleOutsideEvent,
|
||||
trigger: 'hover',
|
||||
delay: 200,
|
||||
excludeSelf: false
|
||||
}"></div>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 描述 |
|
||||
| -- | -- | -- | -- |
|
||||
| `refs` | `Array<string|Vue|HTMLElement>` | `[]` | [^refs] |
|
||||
| `handler` | `function(event: Event): void` | `function() {}` | 外部事件触发时的回调函数，会接收到相应的原生事件对象参数。回调函数的 `event` 参数会根据 `trigger` 参数变成相应的原生事件对象。 |
|
||||
| `trigger` | `string` | `'click'` | 外部事件名，可取的值有：`click`，`mousedown`，`mouseup`，`hover`，`focus`。 |
|
||||
| `delay` | `number` | `0` | 在 `trigger` 为 `hover` 的时候，鼠标移出目标元素 `delay` 毫秒之后，才触发回调函数。如果在 `delay` 毫秒之内，鼠标重新移回了目标元素集合内，就不会触发回调函数。 |
|
||||
| `excludeSelf` | `boolean` | `false` | 在计算目标元素集合的时候，用于判断是否排除自身元素。 |
|
||||
|
||||
^^^refs
|
||||
该参数指定了目标元素集合，在目标元素之外触发指定事件，就会调用传入的回调函数。默认情况下，会将与 `v-outside` 指令绑定的元素算在目标元素之中，不过可以通过 `excludeSelf` 排除掉自身。
|
||||
|
||||
+++类型详情
|
||||
| 类型 | 描述 |
|
||||
| -- | -- |
|
||||
| `string` | 在指令所在组件上下文中，根据 `ref` 查找指定的 DOM 元素集合。 |
|
||||
| `Vue` | 组件实例，直接使用 `vm.$el` 元素。 |
|
||||
| `HTMLElement` | DOM 元素，直接使用。 |
|
||||
+++
|
||||
^^^
|
||||
|
||||
:::warning
|
||||
`Object` 类型提供的参数会覆盖通过指令参数、修饰符指定的参数。
|
||||
:::
|
||||
|
||||
### 修饰符
|
||||
|
||||
对应 `Object` 类型绑定值中的 `trigger`/`delay`/`excludeSelf`。例如：
|
||||
|
||||
```html
|
||||
<div v-outside.hover.200.excludeSelf></div>
|
||||
```
|
||||
|
||||
:::warning
|
||||
在修饰符中的唯一正整数将被识别为 `delay`。
|
||||
:::
|
||||
|
||||
### 参数
|
||||
|
||||
对应 `Object` 绑定值中的 `refs`。值是一个用 `,` 分隔的、表示一到多个 `ref` 的字符串。例如：
|
||||
|
||||
```html
|
||||
<div v-outside:box1,box2></div>
|
||||
```
|
||||
77
one/docs/directives/v-resize.md
Normal file
77
one/docs/directives/v-resize.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# v-resize
|
||||
|
||||
## 简介
|
||||
|
||||
`v-resize` 指令用于检测元素是否发生了尺寸变化。
|
||||
|
||||
## 示例
|
||||
|
||||
[[ demo src="/demo/directives/resize.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)。
|
||||
:::
|
||||
|
||||
### 绑定值
|
||||
|
||||
类型：`function|Object`。
|
||||
|
||||
使用 `function` 类型则绑定值表示 resize 时触发的回调函数。例如：
|
||||
|
||||
```html
|
||||
<div v-resize="handler"></div>
|
||||
```
|
||||
|
||||
使用 `Object` 类型时绑定值可完整配置所有参数。例如：
|
||||
|
||||
```html
|
||||
<div v-resize="{
|
||||
wait: 100,
|
||||
mode: 'debounce',
|
||||
handler: cb,
|
||||
leading: true
|
||||
}"></div>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 描述 |
|
||||
| -- | -- | -- | -- |
|
||||
| `wait` | `number` | `150` | 传递给 `mode` 函数的毫秒数。 |
|
||||
| `mode` | `string` | - | [^mode] |
|
||||
| `handler` | `function` | - | resize 时触发的回调函数。 |
|
||||
| `leading` | `boolean` | `false` | 防抖、节流模式是否在 resize 最初就将执行一次。 |
|
||||
|
||||
:::warning
|
||||
`Object` 类型提供的参数会覆盖通过指令参数、修饰符指定的参数。
|
||||
:::
|
||||
|
||||
^^^mode
|
||||
执行模式，默认为最细粒度。
|
||||
|
||||
+++枚举值
|
||||
| 值 | 描述 |
|
||||
| -- | -- |
|
||||
| `debounce` | 防抖模式。 |
|
||||
| `throttle` | 节流模式。 |
|
||||
+++
|
||||
^^^
|
||||
|
||||
### 修饰符
|
||||
|
||||
对应 `Object` 类型绑定值中的 `mode`/`leading`/`wait`。`leading` 可以与 `debounce`/`throttle` 其中之一同时使用。例如：
|
||||
|
||||
```html
|
||||
<div v-resize.throttle.leading.500="handler"></div>
|
||||
```
|
||||
|
||||
| 值 | 描述 |
|
||||
| -- | -- |
|
||||
| `debounce` | 使用防抖模式，不能与 `throttle` 一同使用。 |
|
||||
| `throttle` | 使用节流模式，不能与 `debounce` 一同使用。 |
|
||||
| `leading` | 使用后，防抖、节流模式在第一次触发 resize 时就将执行一次。 |
|
||||
| <var>wait</var> | 传递给 `mode` 函数的毫秒数，注意这里 <var>wait</var> 是一个变量。 |
|
||||
|
||||
:::warning
|
||||
在修饰符中的唯一正整数将被识别为 `wait`。
|
||||
:::
|
||||
Reference in New Issue
Block a user