复制指令与指令模块化入口

概述

在后台管理系统中，"一键复制"是出现频率极高的交互：复制订单号、复制接口地址、复制一段 JSON、复制错误堆栈……这些动作如果每次都手写 navigator.clipboard.writeText 加一堆降级判断，会产生大量重复代码，而且不同开发者实现的健壮性还不一致。把"复制"抽成一个 Vue 自定义指令 v-copy，是这类高频、低差异交互最划算的收口方式。

指令的价值不只是少写几行代码。它把"触发方式"（点击、长按、双击）、"复制内容来源"（元素文本、绑定值、属性）、"复制成功/失败的反馈"这三件事统一封装起来，业务侧只剩下一个声明式的标记。本文先讲复制指令本身怎么实现，再讲为什么需要一个"指令模块化入口"来统一注册所有指令，避免散落在各处的 app.directive 调用。

学习目标

• 理解 Vue 自定义指令的钩子生命周期，以及指令为什么适合做"DOM 行为增强"这类事情。
• 掌握复制指令的核心实现：优先用 navigator.clipboard，在 insecure context 下降级到 document.execCommand('copy')。
• 学会让指令支持三种内容来源：元素自身文本、绑定值、以及带参数的取值函数。
• 能设计一个可插拔的"指令模块化入口"，用 install 插件形式一次性注册全部指令。
• 区分"指令能做"和"指令不该做"的边界，避免把业务逻辑塞进指令里。

一、为什么复制适合做成指令

复制动作有几个特征：第一，它直接操作 DOM 选区或剪贴板，天然和某个 DOM 节点绑定；第二，触发方式通常是"点一下就复制"，是典型的行为增强；第三，反馈（toast 提示、按钮文字变化）需要就地发生，贴近触发元素。这三个特征正好落在自定义指令的甜区里。

如果用组件实现复制，你得在每个按钮位置包一层 <CopyButton>，要么接受组件结构侵入，要么用 render 函数硬塞。而指令只需要在原元素上写 v-copy="text"，语义清晰、改动最小。这也是为什么这类"高频、低差异、紧贴 DOM"的交互不约而同地走向指令方案。

二、Vue 指令的钩子与生命周期

一个完整的指令对象可以包含 created、beforeMount、mounted、beforeUpdate、updated、beforeUnmount、unmounted 七个钩子。复制指令真正需要的只有 mounted（绑定点击事件）、updated（刷新复制内容）和 unmounted（移除监听、清理定时器）。

import type { Directive, DirectiveBinding } from 'vue'

const vCopy: Directive<HTMLElement, string> = {
  mounted(el, binding) {
    el.addEventListener('click', () => handleCopy(el, binding))
  },
  updated(el, binding) {
    // 绑定值变化时无需重新绑定事件，但可在复制时读取最新值
    ;(el as any).__copyValue = binding.value
  },
  unmounted(el) {
    el.removeEventListener('click', () => handleCopy(el, (el as any).__binding))
  },
}

注意 unmounted 里移除监听时，必须拿到和 mounted 里同一个函数引用，否则移除无效、造成内存泄漏。常见写法是在 mounted 时把处理函数挂到 el 上（el.__handler = handler），卸载时再用同一引用移除。

三、复制指令的核心实现

核心难点不在"复制"本身，而在健壮性。navigator.clipboard.writeText 是现代标准做法，但它有两个前提：页面必须运行在 secure context（https 或 localhost），且需要用户手势触发——指令的 click 事件正好满足。在不满足 secure context 的内网 http 环境下，必须降级到 document.execCommand('copy')。

async function copyText(text: string): Promise<boolean> {
  try {
    if (navigator.clipboard && window.isSecureContext) {
      await navigator.clipboard.writeText(text)
      return true
    }
  } catch {
    // 继续走降级方案
  }
  // 降级：创建临时 textarea、选区、execCommand
  const textarea = document.createElement('textarea')
  textarea.value = text
  textarea.style.position = 'fixed'
  textarea.style.opacity = '0'
  document.body.appendChild(textarea)
  textarea.select()
  let ok = false
  try {
    ok = document.execCommand('copy')
  } catch {
    ok = false
  }
  document.body.removeChild(textarea)
  return ok
}

拿到复制结果后，应当就地给用户反馈。最简方案是触发一个全局 toast（通过事件总线或注入的 message 实例），提示"复制成功"或"复制失败，请手动复制"。指令不要自己去实现 toast 组件，而是调用项目已有的反馈通道，保持职责单一。

四、内容来源与参数设计

指令绑定值可以直接是字符串，也可以是一个对象，用来区分"复制什么"和"反馈文案"。推荐约定：v-copy="text" 复制字符串；v-copy="{ text, tips }" 复制文本并自定义成功提示。如果业务要从元素的某个 data 属性取值，可在 binding.arg 里传属性名，但这会让指令变得更重，通常不推荐。

还有一个细节是"复制元素自身文本"的场景（比如一个展示区，点一下就把显示的文本复制走）。这时绑定值可以省略，指令在 mounted 里记录 el.innerText 作为默认值，点击时优先用绑定值，没有绑定值才退回到元素文本。

五、指令模块化入口

当项目里出现第二个、第三个指令时，散落在 main.ts 里的 app.directive('copy', ...) 会很难维护，也难做统一开关。更好的做法是为所有指令建一个模块化入口：每个指令一个文件，导出指令对象和一个 install 函数，再由一个 index.ts 聚合，最后以一个 Vue 插件形式注册。

// directives/index.ts
import copy from './copy'
import debounce from './debounce'
import permission from './permission'

const directives = { copy, debounce, permission }

export const directivePlugin = {
  install(app: App) {
    Object.entries(directives).forEach(([name, dir]) => {
      app.directive(name, dir)
    })
  },
}

// main.ts
import { directivePlugin } from '@/directives'
app.use(directivePlugin)

这样做的好处是：新增指令只需在 directives/ 下加文件并登记到聚合对象，注册逻辑零改动；后续要做"指令白名单""按环境开关""统一埋点"也都有了统一抓手。本文的复制指令只是入口里的第一个成员，后续防抖、权限等指令都走同一通道。

常见问题

延伸阅读

• 上一篇：VForm 模块收尾与动态组件扩展方向
• 下一篇：防抖节流指令与函数频率控制
• 相关：权限指令与响应式角色订阅