剪贴板 clipboard

通用组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

展示框是只读不是禁用：聚焦即全选，键盘用户照样能用 Ctrl / Cmd + C 自己带走

接口密钥

<script setup lang="ts">
import {
  XhClipboardControl,
  XhClipboardIndicator,
  XhClipboardInput,
  XhClipboardLabel,
  XhClipboardRoot,
  XhClipboardTrigger,
} from "@xihan-ui/vue";

const apiToken = "xh_live_9f2c7a41b6d84e05";
</script>

<template>
  <XhClipboardRoot :value="apiToken">
    <XhClipboardLabel>接口密钥</XhClipboardLabel>
    <XhClipboardControl>
      <XhClipboardInput />
      <XhClipboardTrigger>
        <!-- 两个指示器都常挂 DOM、靠 hidden 互斥显隐，来回切按钮不抖宽 -->
        <XhClipboardIndicator>复制</XhClipboardIndicator>
        <XhClipboardIndicator copied>✓ 已复制</XhClipboardIndicator>
      </XhClipboardTrigger>
    </XhClipboardControl>
  </XhClipboardRoot>
</template>

只要一颗按钮

必备部件只有 root 与 trigger：文本已经在页面上时，展示框与标题都可以省掉

pnpm add @xihan-ui/vue @xihan-ui/styles

<script setup lang="ts">
import { XhClipboardIndicator, XhClipboardRoot, XhClipboardTrigger } from "@xihan-ui/vue";

const install = "pnpm add @xihan-ui/vue @xihan-ui/styles";
</script>

<template>
  <code style="font-size: 13px;">{{ install }}</code>
  <XhClipboardRoot :value="install" :timeout="1500">
    <XhClipboardTrigger>
      <XhClipboardIndicator>复制安装命令</XhClipboardIndicator>
      <XhClipboardIndicator copied>已复制</XhClipboardIndicator>
    </XhClipboardTrigger>
  </XhClipboardRoot>
</template>

状态与失败

写入是异步的也真的会失败：按下先进 copying，写成功才翻成 copied，失败一律退回 idle 并把原因报出来

状态：idle

<script setup lang="ts">
import { ref } from "vue";
import {
  XhClipboardControl,
  XhClipboardIndicator,
  XhClipboardInput,
  XhClipboardRoot,
  XhClipboardTrigger,
} from "@xihan-ui/vue";

const status = ref("idle");
const lastError = ref("");

function onStatusChange(details: { status: string }) {
  status.value = details.status;
}

function onCopyError(details: { error: unknown; value: string }) {
  lastError.value = String(details.error);
}
</script>

<template>
  <!-- timeout 决定“已复制”停留多久，到点自己回落 -->
  <XhClipboardRoot
    value="订单号 A2026-0809-117"
    :timeout="2000"
    @status-change="onStatusChange"
    @copy-error="onCopyError"
  >
    <XhClipboardControl>
      <XhClipboardInput />
      <XhClipboardTrigger>
        <XhClipboardIndicator>复制</XhClipboardIndicator>
        <XhClipboardIndicator copied>✓ 已复制</XhClipboardIndicator>
      </XhClipboardTrigger>
    </XhClipboardControl>
  </XhClipboardRoot>

  <span style="font-size: 13px;">
    状态：{{ status }}
    <template v-if="lastError"> · 上次失败：{{ lastError }}</template>
  </span>
</template>

产物

层	值
自定义元素	<xh-clipboard>
Vue 组件	XhClipboardControl XhClipboardIndicator XhClipboardInput XhClipboardLabel XhClipboardRoot XhClipboardTrigger
组合式函数	useClipboard
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/clipboard.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="clipboard"：root · label · control · input · trigger · indicator

Props

属性	类型	必填	说明
value	string		要复制的文本；缺省即复制空串。
timeout	number		复制成功后指示器保持多久（毫秒），默认 3000；<=0 或非有限数表示不自动回落。
onStatusChange	(details: ClipboardStatusChangeDetails) => void		状态每次落位时通知一次；挂载那一刻的 idle 是初始态，不通知。
onCopyError	(details: ClipboardCopyErrorDetails) => void		写入失败时通知；此时状态已经回到 idle。

状态机

事件：COPY.TRIGGER · COPY.SUCCESS · COPY.ERROR · after.timeout

connect API

useClipboard 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
status	ClipboardStatus
copied	boolean	已经复制成功且还在停留窗口内。指示器与样式的唯一判据。
value	string	当前要复制的文本（prop 缺省时是空串）。
copy	() => void	走一次复制意图，与点按钮同一条路。
getRootProps	() => T['element']
getLabelProps	() => T['label']
getControlProps	() => T['element']
getInputProps	() => T['input']
getTriggerProps	() => T['button']
getIndicatorProps	(props: ClipboardIndicatorProps) => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。