Progress 进度条
展示操作进度或数据占比,有线形、环形、仪表盘三种样式。
引入
ts
import { NsProgress } from '@ns/ui'
基础用法
percentage 是百分比(0~100),默认是线形进度条,右侧显示百分比文字。超出 0~100 时按边界显示,例如 120 显示成 100%。
vue
<template>
<NsSpace direction="vertical" fill>
<NsProgress :percentage="0" />
<NsProgress :percentage="50" />
<NsProgress :percentage="100" />
<NsProgress :percentage="120" />
</NsSpace>
</template>
类型
type 有三种:
line(默认):线形,宽度撑满父元素,文字在右侧。circle:完整的圆环,从顶部顺时针增长,文字在中间。dashboard:仪表盘,底部留出 1/4 缺口,从缺口左侧顺时针增长。
vue
<template>
<NsSpace direction="vertical" fill>
<div class="row">
<span class="row-label">line</span>
<NsProgress :percentage="75" />
</div>
<NsSpace wrap size="large">
<div class="cell">
<NsProgress type="circle" :percentage="75" />
<span class="row-label">circle</span>
</div>
<div class="cell">
<NsProgress type="dashboard" :percentage="75" />
<span class="row-label">dashboard</span>
</div>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row {
display: flex;
align-items: center;
gap: var(--ns-spacing-3);
}
.cell {
display: flex;
flex-direction: column;
align-items: center;
gap: var(--ns-spacing-2);
}
.row-label {
flex-shrink: 0;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.cell .row-label {
width: auto;
}
</style>
状态
status 设为 success、warning、exception 时,进度条和外置文字(环形、仪表盘是中间的文字)使用对应的成功色、警告色、危险色;不设时是主色。三种类型都支持:
vue
<template>
<NsSpace direction="vertical" fill>
<div class="row">
<span class="row-label">不设置</span>
<NsProgress :percentage="50" />
</div>
<div class="row">
<span class="row-label">success</span>
<NsProgress :percentage="70" status="success" />
</div>
<div class="row">
<span class="row-label">warning</span>
<NsProgress :percentage="50" status="warning" />
</div>
<div class="row">
<span class="row-label">exception</span>
<NsProgress :percentage="30" status="exception" />
</div>
<NsSpace wrap size="large">
<div class="cell">
<NsProgress type="circle" :percentage="50" :width="100" />
<span class="row-label">不设置</span>
</div>
<div class="cell">
<NsProgress type="circle" :percentage="70" :width="100" status="success" />
<span class="row-label">success</span>
</div>
<div class="cell">
<NsProgress type="circle" :percentage="50" :width="100" status="warning" />
<span class="row-label">warning</span>
</div>
<div class="cell">
<NsProgress type="circle" :percentage="30" :width="100" status="exception" />
<span class="row-label">exception</span>
</div>
</NsSpace>
<NsSpace wrap size="large">
<div class="cell">
<NsProgress type="dashboard" :percentage="50" :width="100" />
<span class="row-label">不设置</span>
</div>
<div class="cell">
<NsProgress type="dashboard" :percentage="70" :width="100" status="success" />
<span class="row-label">success</span>
</div>
<div class="cell">
<NsProgress type="dashboard" :percentage="50" :width="100" status="warning" />
<span class="row-label">warning</span>
</div>
<div class="cell">
<NsProgress type="dashboard" :percentage="30" :width="100" status="exception" />
<span class="row-label">exception</span>
</div>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row {
display: flex;
align-items: center;
gap: var(--ns-spacing-3);
}
.cell {
display: flex;
flex-direction: column;
align-items: center;
gap: var(--ns-spacing-2);
}
.row-label {
flex-shrink: 0;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.cell .row-label {
width: auto;
}
</style>
文字位置
线形进度条的文字有三种显示方式:
- 外置(默认):在进度条右侧,给文字留出“100%”的宽度,几条进度条上下排列时长度一致。
- 内置:
text-inside把文字放进已完成那一段的末端,文字是白色。需要配合较粗的stroke-width(建议不小于 16),否则文字放不下。设置了status时文字仍是白色,进度条换成状态色。 - 不显示:
show-text设为false。
环形和仪表盘的文字固定在中间,text-inside 对它们无效,show-text 设为 false 时不显示。
vue
<template>
<NsSpace direction="vertical" fill>
<div class="row">
<span class="row-label">外置(默认)</span>
<NsProgress :percentage="70" />
</div>
<div class="row">
<span class="row-label">内置</span>
<NsProgress :percentage="70" text-inside :stroke-width="20" />
</div>
<div class="row">
<span class="row-label">内置 + 状态</span>
<NsProgress :percentage="70" text-inside :stroke-width="20" status="success" />
</div>
<div class="row">
<span class="row-label">不显示</span>
<NsProgress :percentage="70" :show-text="false" />
</div>
<NsSpace wrap size="large">
<div class="cell">
<NsProgress type="circle" :percentage="70" :width="100" />
<span class="row-label">环形</span>
</div>
<div class="cell">
<NsProgress type="circle" :percentage="70" :width="100" :show-text="false" />
<span class="row-label">环形不显示文字</span>
</div>
<div class="cell">
<NsProgress type="dashboard" :percentage="70" :width="100" :show-text="false" />
<span class="row-label">仪表盘不显示文字</span>
</div>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row {
display: flex;
align-items: center;
gap: var(--ns-spacing-3);
}
.cell {
display: flex;
flex-direction: column;
align-items: center;
gap: var(--ns-spacing-2);
}
.row-label {
flex-shrink: 0;
width: 88px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.cell .row-label {
width: auto;
}
</style>
粗细和大小
stroke-width 在线形里是进度条的高度,在环形、仪表盘里是圆环的线宽,默认 6px。width 是环形、仪表盘的画布宽度(也是高度),默认 126px,对线形无效。
vue
<template>
<NsSpace direction="vertical" fill>
<div class="row">
<span class="row-label">4px</span>
<NsProgress :percentage="60" :stroke-width="4" />
</div>
<div class="row">
<span class="row-label">6px(默认)</span>
<NsProgress :percentage="60" />
</div>
<div class="row">
<span class="row-label">10px</span>
<NsProgress :percentage="60" :stroke-width="10" />
</div>
<div class="row">
<span class="row-label">16px</span>
<NsProgress :percentage="60" :stroke-width="16" />
</div>
<NsSpace wrap size="large" align="end">
<NsProgress type="circle" :percentage="60" :width="80" :stroke-width="4" />
<NsProgress type="circle" :percentage="60" />
<NsProgress type="circle" :percentage="60" :width="180" :stroke-width="12" />
<NsProgress type="dashboard" :percentage="60" :width="180" :stroke-width="16" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row {
display: flex;
align-items: center;
gap: var(--ns-spacing-3);
}
.row-label {
flex-shrink: 0;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
自定义颜色
color 有三种写法:
- 字符串:固定颜色。
- 函数
(percentage) => string:按当前百分比返回颜色。 - 颜色数组:按百分比在相邻两个颜色之间渐变。例如两个颜色时,0% 是第一个、100% 是第二个、50% 是两者的中间色。只有 6 位或 3 位 hex 颜色能渐变;其他写法(
'red'、CSS 变量)在两个颜色之间按位置取其一。只有一个颜色时直接用它,空数组时用主色。
设置了 status 时,状态色优先于 color。
vue
<script setup lang="ts">
const color = (percentage: number) => {
if (percentage < 30) return 'var(--ns-color-danger)'
if (percentage < 70) return 'var(--ns-color-warning)'
return 'var(--ns-color-success)'
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsProgress :percentage="60" color="#ff6b6b" />
<NsProgress :percentage="50" :color="color" />
<NsProgress :percentage="80" :color="['#ff6b6b', '#4ecdc4']" />
</NsSpace>
</template>
环形和仪表盘也一样:
vue
<script setup lang="ts">
const color = (percentage: number) => {
if (percentage < 30) return 'var(--ns-color-danger)'
if (percentage < 70) return 'var(--ns-color-warning)'
return 'var(--ns-color-success)'
}
</script>
<template>
<NsSpace wrap size="large">
<NsProgress type="circle" :percentage="60" color="#ff6b6b" />
<NsProgress type="circle" :percentage="20" :color="color" />
<NsProgress type="dashboard" :percentage="80" :color="['#ff6b6b', '#ffd166', '#4ecdc4']" />
</NsSpace>
</template>
自定义文字
format 接收当前百分比(已截断到 0~100),返回要显示的文字;showText 为 false 时不显示文字。
vue
<script setup lang="ts">
const format = (percentage: number) => (percentage === 100 ? '已完成' : `${percentage} 分`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsProgress :percentage="60" :format="format" />
<NsProgress :percentage="40" :show-text="false" />
<NsSpace wrap size="large">
<NsProgress type="circle" :percentage="100" status="success" :format="format" />
<NsProgress type="dashboard" :percentage="85" :format="format" />
</NsSpace>
</NsSpace>
</template>
动态进度
点按钮增减进度,宽度和弧长变化时有 0.3 秒的过渡动画。这里到 100% 时把 status 设为 success,仪表盘用颜色数组从红色渐变到绿色。
vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsButton, NsButtonGroup, NsProgress, NsSpace } from '@ns/ui'
import type { ProgressStatus } from '@ns/ui'
const percentage = ref(20)
const status = computed<ProgressStatus | undefined>(() =>
percentage.value === 100 ? 'success' : undefined
)
const decrease = () => {
percentage.value = Math.max(0, percentage.value - 10)
}
const increase = () => {
percentage.value = Math.min(100, percentage.value + 10)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsProgress :percentage="percentage" :status="status" />
<NsSpace wrap size="large">
<NsProgress type="circle" :percentage="percentage" :status="status" />
<NsProgress type="dashboard" :percentage="percentage" :color="['#ff6b6b', '#4ecdc4']" />
</NsSpace>
<div>
<NsButtonGroup>
<NsButton icon="minus" :disabled="percentage <= 0" @click="decrease">减少 10%</NsButton>
<NsButton icon="plus" :disabled="percentage >= 100" @click="increase">增加 10%</NsButton>
</NsButtonGroup>
</div>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| percentage | number | 0 | 百分比,超出 0~100 时按边界显示 |
| type | 'line' | 'circle' | 'dashboard' | 'line' | 类型 |
| status | 'success' | 'warning' | 'exception' | - | 状态,设置后使用对应的功能色,优先于 color |
| strokeWidth | number | 6 | 线形是进度条的高度,环形和仪表盘是圆环的线宽(px) |
| textInside | boolean | false | 文字是否显示在进度条里面,只对线形有效 |
| color | string | string[] | ((percentage: number) => string) | - | 进度条颜色,数组表示在多个颜色之间按百分比渐变,见“自定义颜色” |
| width | number | 126 | 环形和仪表盘的画布宽度(px) |
| showText | boolean | true | 是否显示文字 |
| format | (percentage: number) => string | - | 自定义文字内容,参数是截断到 0~100 之后的百分比 |
类型
ts
import type { ProgressProps, ProgressType, ProgressStatus, ProgressColor } from '@ns/ui'
type ProgressType = 'line' | 'circle' | 'dashboard'
type ProgressStatus = 'success' | 'warning' | 'exception'
type ProgressColorFn = (percentage: number) => string
type ProgressColor = string | string[] | ProgressColorFn
interface ProgressProps {
percentage?: number
type?: ProgressType
status?: ProgressStatus
strokeWidth?: number
textInside?: boolean
color?: ProgressColor
width?: number
showText?: boolean
format?: (percentage: number) => string
}
注意事项
- 组件没有插槽,文字内容只能通过
format定制。 - 数组形式的
color是在颜色之间渐变,不是按百分比分段取固定颜色;需要分段取色时用函数形式的color。 - 根元素带
role="progressbar"和aria-valuenow、aria-valuemin、aria-valuemax,读屏软件能读出当前进度。 textInside的文字是白色,放在已完成的那一段里;百分比很小时那一段太短,文字可能放不下。- 百分比为 0 时,环形和仪表盘的进度弧不显示(线宽为 0),只显示灰色轨道。
优化点
- [x] 支持渐变色进度条(数组形式的
color) - [x] 支持动画过渡效果(宽度、弧长变化时有 0.3 秒过渡)
- [ ] 支持分段进度显示
- [ ] 支持进度条点击交互
- [ ] 支持默认插槽自定义文字