CopyButton 使用手册

v1.0.2 · @snowui-design-system/components

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

将文字或代码复制到剪贴板，并提供短暂的成功反馈，适合链接、标识符和安装命令。

使用选择

用于复制内容并显示复制反馈。复用其公开 getText / writeText 入口，不在页面再维护重复的成功状态。

静态内容使用 text，动态内容使用 getText；writeText 可替换实际复制实现。
onCopy / onCopyError 处理业务反馈；showText=false 隐藏文字，成功反馈时间由 feedbackDuration 控制。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { CopyButton } from '@snowui-design-system/components';</script> <CopyButton text="pnpm add @snowui-design-system/components">Copy</CopyButton>

API

关键字	类型	默认值	描述
text	`string`	—	要复制的静态文本；getText 存在时优先使用其返回值，两者均未提供时复制空字符串。
getText	`() => string \| Promise<string>`	—	点击时读取复制内容，可返回 Promise；优先于 text。求值与写入剪贴板均在 pending 阶段，失败进入 onCopyError。
writeText	`(text: string) => void \| Promise<void>`	`writeClipboardText`	替换实际复制操作；Promise 完成后显示成功，抛出错误进入失败反馈。用于已有业务复制回调，避免重复写入剪贴板。默认行为：内置剪贴板写入。
feedbackDuration	`number`	`1600`	复制成功或失败后恢复 idle 的等待时间，单位 ms，负值按 0 处理；pending 与反馈期都忽略重复点击。
showText	`boolean`	`true`	显示图标后的 children 或默认复制文字；默认文字随 LocaleProvider 切换，中文“复制”、英文“Copy”；false 时仅显示状态图标；bare 模式无外壳，其余模式启用 Button.iconOnly。
ariaLabel	`string`	—	覆盖可访问名称；纯图标模式默认按成功状态使用 LocaleProvider 的“已复制”/“复制”或“Copied”/“Copy”，带文字模式默认由内容命名。
disabled	`boolean`	`false`	阻止新的复制操作；已开始的异步复制不会因此取消。
children	`Snippet`	`—（复制）`	showText=true 时替换图标后的文字，成功时仍保持该内容；false 时忽略。
icon	`Snippet`	`—（Copy 图标）`	替换非成功状态的图标；pending 和 error 仍使用该图标。
successIcon	`Snippet`	`—（Check 图标）`	复制成功时的图标内容；优先于 successContent，通过内部状态内容替换显示。
successContent	`Snippet`	—	成功图标区域的替代内容，仅在未提供 successIcon 时使用；不会替换按钮文字。
onCopy	`(text: string) => void`	—	剪贴板写入成功后接收实际复制的文本；此时组件已进入 success 状态。
onCopyError	`(error: unknown) => void`	—	动态内容读取或剪贴板写入失败时接收错误，组件进入 error 并等待反馈期复位。
onclick	`(event: MouseEvent) => void`	—	仅 idle 且未禁用时，在读取文本和复制前调用；preventDefault() 不会取消复制，反馈期内不调用。

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

使用

<script lang="ts">  import { CopyButton } from "@snowui-design-system/components";</script> <CopyButton text="SnowUI" variant="outline" />

平铺 Button 兼容 Props。text 提供静态内容，getText 提供同步或异步动态内容；复制成功触发 onCopy，失败触发 onCopyError。从复制开始到成功反馈结束的整个非 idle 阶段禁止重复触发；此时不设置 disabled，不改变按钮视觉，只关闭 Button 点击反馈并忽略后续点击。成功反馈在 feedbackDuration 后复位。不提供 parts。

showText={false} 启用无文字模式，只显示 Copy / Check 图标，并自动提供复制状态的 aria-label。图标变化使用内部 Frame 的 150ms replacement appear：复制成功显示 Check，反馈结束恢复 Copy；Button 本身不进入 Active/toggle 视觉。带文字模式下文字始终保持当前 LocaleProvider 的“复制”或“Copy”，只有图标执行内容替换动效。

API

其他兼容视觉、链接与事件入口参见 Button。CopyButton 接管 children、onclick、disabled、currentState、stateContent、whileActive、Click 和 Active，不能用这些宿主字段替代复制状态。

此区域的内容受保护。AI 在修改此区域前必须请求用户审查。

CopyButton 样式覆盖

先阅读完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按样式选择与改写顺序使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

变量	用途与默认参考
`--snowui-copy-button-motion-duration-override`	default: 150ms; Button hover / click

设计指南 · Token · 组合边界

CopyButton 类型与状态

必填属性：无具名必填属性。

可双向绑定：本组件未声明具名双向绑定属性；状态更新通过公开回调或所属宿主处理。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。

ButtonProps

来源：components/src/components/CopyButton.svelte

type ButtonProps = ComponentProps<typeof Button>;