mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-20 02:03:35 +08:00
Restore keyboard navigation and fix page refresh, icons, and table interactions. Guard concurrent edits and align Mock persistence with the API contracts.
132 lines
5.9 KiB
Markdown
132 lines
5.9 KiB
Markdown
# 指令
|
||
|
||
<script setup>
|
||
import AdminExample from '../examples/AdminExample.vue'
|
||
import DebounceDemo from '../examples/DebounceDemo.vue'
|
||
</script>
|
||
|
||
应用在 `main.ts` 调用 `setupDirectives(app)`。注册器查找 `packages/directives/src/modules/<name>/index.ts`,调用默认导出的工厂,将返回的 Vue Directive 以目录名注册。SFC 中可直接用 `v-<name>`;从文件名和源码进入可查各指令的绑定类型。
|
||
|
||
## 交互示例
|
||
|
||
在同一示例操作复制、节流、防抖、文本省略、波纹与禁用。下方防抖小例可以快速对照计数。
|
||
|
||
<AdminExample path="/directive" title="六种指令的交互示例" :height="550" />
|
||
|
||
::: details 查看完整指令示例源码
|
||
<<< @/../admin/src/views/demo/directive/index.tsx
|
||
:::
|
||
|
||
## v-copy
|
||
|
||
绑定要复制的字符串;绑定值改变时销毁并重建 ClipboardJS 实例,卸载时销毁。Ray Admin 注册时接入消息提示。独立使用 `createCopyDirective` 时可提供自己的结果回调。复制应由用户点击触发。数字等值请先显式转为字符串。
|
||
|
||
```vue
|
||
<template>
|
||
<button type="button" v-copy="'ORD-001'">复制订单号</button>
|
||
</template>
|
||
```
|
||
|
||
[源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/copy/index.ts)
|
||
|
||
## v-debounce 与 v-throttle
|
||
|
||
连续点击按钮,停止 500ms 后,防抖只执行一次。
|
||
|
||
<DebounceDemo />
|
||
|
||
::: details 查看示例源码
|
||
<<< @/examples/DebounceDemo.vue
|
||
:::
|
||
|
||
两者都接收 `{ func, trigger?, wait?, options? }`。`func` 必须是函数并可接收原生事件;`trigger` 默认 `'click'`,`wait` 默认 `500` 毫秒,`options` 转给 Lodash 的对应方法。防抖适合在连续输入停止后处理,节流适合限制持续触发的频率。
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { ref } from 'vue'
|
||
|
||
const keyword = ref('')
|
||
const requestedKeyword = ref('')
|
||
const clicks = ref(0)
|
||
|
||
const applySearch = () => {
|
||
requestedKeyword.value = keyword.value
|
||
}
|
||
const countClick = () => {
|
||
clicks.value += 1
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<input
|
||
v-model="keyword"
|
||
v-debounce="{ func: applySearch, trigger: 'input', wait: 300 }"
|
||
/>
|
||
<p>已提交的查询词:{{ requestedKeyword }}</p>
|
||
<button type="button" v-throttle="{ func: countClick, wait: 1000 }">
|
||
点击次数 {{ clicks }}
|
||
</button>
|
||
</template>
|
||
```
|
||
|
||
- `options.leading` / `trailing` 决定在等待周期首尾是否执行;防抖还可设 `maxWait`。挂载时读取绑定值,更新不会重绑。若回调依赖变动数据,让原函数在执行时读取响应式值。
|
||
- 同一指令可以绑定多个元素。每个元素独立计时,卸载时只清理自己的监听器和待执行回调。需要动态修改间隔时,可更换元素的 `key` 重新绑定。
|
||
- 防抖和节流只约束事件触发,异步请求仍需独立处理取消、并发或幂等。
|
||
|
||
[防抖源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/debounce/index.ts) · [节流源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/throttle/index.ts)
|
||
|
||
## v-ellipsis
|
||
|
||
`width` 必填,数字按像素;字符串可传 CSS 尺寸。`type: 'block'` 做单行省略,`type: 'line'` 使用 `line` 行截断,默认按单行处理。`popoverText: true` 把当前文本写入原生 `title`,不创建 Popover。挂载和更新时写入样式;切换模式或关掉悬浮文本不会自动删除上一次写入的样式或 `title`。经常切换的场景可以改用组件库的省略组件,或切换节点 `key`。
|
||
|
||
```vue
|
||
<template>
|
||
<p v-ellipsis="{ type: 'line', line: 2, width: 240, popoverText: true }">
|
||
这里放较长的说明文字,超出两行后会被省略。
|
||
</p>
|
||
</template>
|
||
```
|
||
|
||
[源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/ellipsis/index.ts)
|
||
|
||
## v-ripple
|
||
|
||
省略绑定值或传 `true` 启用,`false` 关闭。绑定对象 `{ class: '...' }` 可指定波纹样式。`.center` 从中心扩散,`.circle` 使用圆形计算。通过 pointer 事件渲染,属于视觉反馈,交互语义仍由外层按钮负责。
|
||
|
||
```vue
|
||
<template>
|
||
<button type="button" v-ripple.center.circle>查看详情</button>
|
||
</template>
|
||
```
|
||
|
||
[源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/ripple/index.ts) · [绑定与清理](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/ripple/utils.ts)
|
||
|
||
## v-disabled
|
||
|
||
原生表单控件使用布尔 `disabled` 属性。表单、容器和自定义控件的根元素使用 `inert`,禁用期间子树退出键盘焦点顺序,指针也无法操作。绑定值恢复为 `false` 后即可继续交互。组件库提供 `disabled` prop 时优先使用它。
|
||
|
||
[源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/modules/disabled/index.ts)
|
||
|
||
## 新增指令
|
||
|
||
每个指令放在单独目录,工厂默认导出。可用 `CustomDirectiveFC<HTMLElement, T>` 标注绑定值。在 `mounted` 取得元素,在 `updated` 处理值更新,在 `beforeUnmount` 释放事件、计时器和第三方实例。多个元素需要独立数据时,把状态放在元素关联的 `WeakMap`,避免用单个变量保存全部实例的资源。
|
||
|
||
```ts
|
||
import type { CustomDirectiveFC } from '@/directives/types'
|
||
|
||
const focusWhen: CustomDirectiveFC<HTMLElement, boolean> = () => ({
|
||
mounted(el, { value }) {
|
||
if (value) el.focus()
|
||
},
|
||
updated(el, { value, oldValue }) {
|
||
if (value && !oldValue) el.focus()
|
||
},
|
||
})
|
||
|
||
export default focusWhen
|
||
```
|
||
|
||
将示例保存为 `packages/directives/src/modules/focus-when/index.ts`,在组件中用 `v-focus-when`。目录名按现有约定用单段小写 kebab-case。注册器要求默认导出函数,缺失会抛错。
|
||
|
||
[注册入口](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/index.ts) · [指令类型](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/directives/src/types.ts)
|