Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
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 秒过渡)
- [ ] 支持分段进度显示
- [ ] 支持进度条点击交互
- [ ] 支持默认插槽自定义文字