RingProgress 环形进度

以圆环的弧长表示任务完成的比例。

72%

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

export default function Demo() {
  return <RingProgress value={72} showValue />
}

tsx

用法

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

value 与 max 的含义与 Progress 相同，弧长按两者的比例从顶部起顺时针绘制。中心默认为空，showValue 在中心显示百分比。

40%

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

export default function Demo() {
  return (
    <Inline gap="lg" align="center">
      <RingProgress value={40} />
      <RingProgress value={40} showValue />
    </Inline>
  )
}

tsx

示例

中心内容

children 替换中心的内容，例如完成后显示一个图标，或者用 format 改写数值文字。

3/8

'use client'

import { Check } from 'lucide-react'
import { Inline, RingProgress } from '@hina-ui/react'

const format = (value: number, max: number) => `${value}/${max}`

export default function Demo() {
  return (
    <Inline gap="lg" align="center">
      <RingProgress value={100} tone="success">
        <Check className="text-success size-6" />
      </RingProgress>
      <RingProgress value={3} max={8} showValue format={format} />
    </Inline>
  )
}

tsx

标题

label 显示在圆环下方。

58%

已读

91%

已收藏

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

export default function Demo() {
  return (
    <Inline gap="xl" align="start">
      <RingProgress value={58} showValue label="已读" />
      <RingProgress value={91} showValue label="已收藏" tone="info" />
    </Inline>
  )
}

tsx

数值变化

value 变化时弧长平滑过渡，增加与减少都是如此。

30%

'use client'

import { useState } from 'react'
import { Button, Inline, RingProgress, Stack } from '@hina-ui/react'

export default function Demo() {
  const [value, setValue] = useState(30)
  const step = (delta: number) => {
    setValue(current => Math.min(100, Math.max(0, current + delta)))
  }
  return (
    <Stack gap="md" align="center">
      <RingProgress value={value} showValue size="lg" />
      <Inline gap="sm">
        <Button
          size="sm"
          variant="soft"
          tone="neutral"
          disabled={value === 0}
          onClick={() => step(-10)}
        >
          减 10
        </Button>
        <Button
          size="sm"
          variant="soft"
          tone="neutral"
          disabled={value === 100}
          onClick={() => step(10)}
        >
          加 10
        </Button>
      </Inline>
    </Stack>
  )
}

tsx

尺寸

三档直径，md 是默认值。环的粗细与中心文字随直径一同变化。

60%

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

export default function Demo() {
  return (
    <Inline gap="lg" align="center">
      <RingProgress value={60} size="sm" showValue />
      <RingProgress value={60} showValue />
      <RingProgress value={60} size="lg" showValue />
    </Inline>
  )
}

tsx

色调

tone 决定弧的颜色，默认是强调色。

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

export default function Demo() {
  return (
    <Inline gap="lg" align="center">
      <RingProgress value={70} />
      <RingProgress value={70} tone="neutral" />
      <RingProgress value={100} tone="success" />
      <RingProgress value={70} tone="warning" />
      <RingProgress value={70} tone="danger" />
      <RingProgress value={70} tone="info" />
    </Inline>
  )
}

tsx

未知进度

不传 value 时表示总量未知，四分之一长的弧绕圆环旋转。

正在连接

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

export default function Demo() {
  return <RingProgress label="正在连接" />
}

tsx

行为

弧从顶部起顺时针绘制，两端为圆头；value 为 0 时不绘制。
value 变化时弧长平滑过渡，时长与曲线取自动效变量；越界的 value 按端点处理。
未知进度的旋转与 Spinner 同一节奏；系统开启减弱动态效果时旋转停止，弧保持可见。

API

Props

属性	类型	默认值	说明
`value`	`number \| null`	`null`	当前进度，不传表示未知进度
`max`	`number`	`100`	总量
`label`	`string`	—	圆环下方的标题
`showValue`	`boolean`	`false`	是否在中心显示数值文字
`format`	`(value: number, max: number) => string`	百分比	数值文字的格式
`tone`	`'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'info'`	`'accent'`	弧的颜色
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	直径
`className`	`string`	—	追加至根元素的类名

其余属性透传到带 role="progressbar" 的圆环元素上。

内容属性

属性	说明
`children`	中心内容，默认为 `showValue` 的数值

用法

示例

中心内容

标题

数值变化

尺寸

色调

未知进度

行为

无障碍

API

Props

内容属性