CopyButton 复制按钮

将一段文本写入剪贴板的按钮，并给出复制成功的反馈。

pnpm add @hina-ui/react

import { Code, CopyButton, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline align="center">
      <Code>pnpm add @hina-ui/react</Code>
      <CopyButton text="pnpm add @hina-ui/react" />
    </Inline>
  )
}

tsx

用法

import { CopyButton } from '@hina-ui/react'

text 是必填属性，它的内容会写入剪贴板。复制成功后，图标由复制切换为选中标记，按钮的名称同时变为“已复制”，两秒后自动恢复。

import { CopyButton } from '@hina-ui/react'

export default function Demo() {
  return <CopyButton text="Hina UI" />
}

tsx

示例

尺寸

默认为 sm。复制按钮通常紧跟在一段文本或者一行命令之后，sm 与相邻文字的高度最为接近。

import { CopyButton, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline align="center">
      <CopyButton size="sm" text="小号" />
      <CopyButton size="md" text="中号" />
      <CopyButton size="lg" text="大号" />
    </Inline>
  )
}

tsx

名称与提示

默认名称为“复制”。如果页面上有多个复制按钮，应当通过 label 说明各自复制的内容，并且打开 tooltip，便于在点击之前区分。

复制成功之后名称固定切换为“已复制”，自定义的名称在这段时间内不显示。

import { CopyButton, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline align="center">
      <CopyButton text="ssh://git@example.com/hina.git" label="复制仓库地址" tooltip />
      <CopyButton text="hina-2f9c41" label="复制订单编号" tooltip />
    </Inline>
  )
}

tsx

复位时长

timeout 决定成功状态持续的时间，默认为 2000 毫秒。如果按钮位于较长的表单中或者页面的边缘，可以适当延长，便于使用者注意到反馈。

import { CopyButton, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline align="center">
      <CopyButton text="默认两秒" />
      <CopyButton text="五秒后复位" timeout={5000} />
    </Inline>
  )
}

tsx

复制回调

复制成功时组件会调用 onCopied，参数为写入剪贴板的文本。失败时不触发。

已复制 0 次

'use client'

import { useState } from 'react'
import { CopyButton, Inline, Text } from '@hina-ui/react'

export default function Demo() {
  const [count, setCount] = useState(0)
  return (
    <Inline align="center">
      <CopyButton text="hina@example.com" onCopied={() => setCount(count => count + 1)} />
      <Text tone="muted">已复制 {count} 次</Text>
    </Inline>
  )
}

tsx

剪贴板的限制

浏览器只在安全上下文中提供剪贴板接口，页面需要通过 HTTPS 或者 localhost 访问。在 file:// 打开的页面以及部分内嵌页面中，写入会被拒绝。

写入失败时按钮不会进入成功状态，图标与名称都保持原样，也不会调用 onCopied。

API

Props

属性	类型	默认值	说明
`text`	`string`	—	必填。写入剪贴板的文本
`label`	`string`	复制	按钮的无障碍名称
`size`	`'sm' \| 'md' \| 'lg'`	`'sm'`	尺寸
`timeout`	`number`	`2000`	成功状态持续的毫秒数
`tooltip`	`boolean`	`false`	是否显示提示
`disabled`	`boolean`	`false`	是否不可用
`className`	`string`	—	追加至按钮的类名

回调

回调	参数	说明
`onCopied`	`text: string`	写入剪贴板成功时触发

用法

示例

尺寸

名称与提示

复位时长

复制回调

剪贴板的限制

无障碍

API

Props

回调