为 Vue 构建的界面语言。 v1.7.16 已发布
UI
开始设计规范组件变更记录
GitHub 仓库10

Progress 进度条

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

源码
上传中62%
<script setup lang="ts">
  import { Progress } from '@hina-ui/vue'
</script>

<template>
  <Progress :value="62" label="上传中" show-value class="w-80" />
</template>
vue

用法

import { Progress } from '@hina-ui/vue'
ts

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

<script setup lang="ts">
  import { Progress } from '@hina-ui/vue'
</script>

<template>
  <Progress :value="40" class="w-80" />
</template>
vue

示例

标题与数值

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

正在同步收藏
正在同步收藏25%
25%
<script setup lang="ts">
  import { Progress, Stack } from '@hina-ui/vue'
</script>

<template>
  <Stack gap="lg" class="w-80">
    <Progress :value="25" label="正在同步收藏" />
    <Progress :value="25" label="正在同步收藏" show-value />
    <Progress :value="25" show-value />
  </Stack>
</template>
vue

数值变化

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

下载中30%
<script setup lang="ts">
  import { ref } from 'vue'
  import { Button, Inline, Progress, Stack } from '@hina-ui/vue'

  const value = ref(30)
  const step = (delta: number) => {
    value.value = Math.min(100, Math.max(0, value.value + delta))
  }
</script>

<template>
  <Stack gap="md" class="w-80">
    <Progress :value="value" label="下载中" show-value />
    <Inline gap="sm">
      <Button size="sm" variant="soft" tone="neutral" :disabled="value === 0" @click="step(-10)">
        减 10
      </Button>
      <Button size="sm" variant="soft" tone="neutral" :disabled="value === 100" @click="step(10)">
        加 10
      </Button>
    </Inline>
  </Stack>
</template>
vue

数值格式

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

已处理3 / 8 个文件
<script setup lang="ts">
  import { Progress } from '@hina-ui/vue'

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

<template>
  <Progress :value="3" :max="8" label="已处理" show-value :format="format" class="w-80" />
</template>
vue

尺寸

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

<script setup lang="ts">
  import { Progress, Stack } from '@hina-ui/vue'
</script>

<template>
  <Stack gap="lg" class="w-80">
    <Progress :value="60" size="sm" />
    <Progress :value="60" />
    <Progress :value="60" size="lg" />
  </Stack>
</template>
vue

色调

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

<script setup lang="ts">
  import { Progress, Stack } from '@hina-ui/vue'
</script>

<template>
  <Stack gap="lg" class="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>
</template>
vue

未知进度

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

正在连接
<script setup lang="ts">
  import { Progress } from '@hina-ui/vue'
</script>

<template>
  <Progress label="正在连接" class="w-80" />
</template>
vue

行为

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

无障碍

  • 轨道带 role="progressbar"，aria-valuenow、aria-valuemin 与 aria-valuemax 随 value 与 max 给出；未知进度时不设 aria-valuenow。
  • 无障碍名优先取 label，没有 label 时取数值文字，未知进度时取界面语言中的“加载中”。
  • 传入 format 时其结果同时写入 aria-valuetext，辅助技术朗读的是格式化后的文字而不是原始数字。

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'
高度
class
string
—
追加至根元素的类名

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