Progress 进度条

以横条的填充长度表示任务完成的比例。

上传中62%

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

export default function Demo() {
  return <Progress value={62} label="上传中" showValue className="w-80" />
}

tsx

用法

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

value 是当前进度，max 是总量，默认为 100。进度条按两者的比例填充，value 变化时填充长度平滑过渡。

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

export default function Demo() {
  return <Progress value={40} className="w-80" />
}

tsx

示例

标题与数值

label 显示在进度条上方，showValue 在同一行的末尾显示百分比。

正在同步收藏

正在同步收藏25%

25%

import { Progress, Stack } from '@hina-ui/react'

export default function Demo() {
  return (
    <Stack gap="lg" className="w-80">
      <Progress value={25} label="正在同步收藏" />
      <Progress value={25} label="正在同步收藏" showValue />
      <Progress value={25} showValue />
    </Stack>
  )
}

tsx

数值变化

value 变化时填充长度平滑过渡，增加与减少都是如此，数值文字随之更新。

下载中30%

'use client'

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

export default function Demo() {
  const [value, setValue] = useState(30)
  const step = (delta: number) => {
    setValue(Math.min(100, Math.max(0, value + delta)))
  }

  return (
    <Stack gap="md" className="w-80">
      <Progress value={value} label="下载中" showValue />
      <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

数值格式

format 接收当前值与总量，返回要显示的文字。这段文字同时作为辅助技术朗读的数值。

已处理3 / 8 个文件

'use client'

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

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

export default function Demo() {
  return <Progress value={3} max={8} label="已处理" showValue format={format} className="w-80" />
}

tsx

尺寸

三档高度，md 是默认值；sm 用于列表行内等紧凑位置，lg 用于独立成块的进度。

import { Progress, Stack } from '@hina-ui/react'

export default function Demo() {
  return (
    <Stack gap="lg" className="w-80">
      <Progress value={60} size="sm" />
      <Progress value={60} />
      <Progress value={60} size="lg" />
    </Stack>
  )
}

tsx

色调

tone 决定填充的颜色，默认是强调色。完成、警告、失败等状态可以换用对应的语义色。

import { Progress, Stack } from '@hina-ui/react'

export default function Demo() {
  return (
    <Stack gap="lg" className="w-80">
      <Progress value={70} />
      <Progress value={70} tone="neutral" />
      <Progress value={100} tone="success" />
      <Progress value={70} tone="warning" />
      <Progress value={70} tone="danger" />
      <Progress value={70} tone="info" />
    </Stack>
  )
}

tsx

未知进度

不传 value 时表示总量未知，一段填充沿轨道反复扫过。

正在连接

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

export default function Demo() {
  return <Progress label="正在连接" className="w-80" />
}

tsx

行为

value 变化时填充长度平滑过渡，时长与曲线取自动效变量。
越界的 value 按端点处理：小于 0 视为 0，大于 max 视为 max。
未知进度的扫动时长取自动效变量；系统开启减弱动态效果时扫动停止，填充段停在轨道中央。

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" 的轨道元素上。

用法

示例

标题与数值

数值变化

数值格式

尺寸

色调

未知进度

行为

无障碍

API

Props