Naive UI Progress 进度条组件完整指南:类型、属性与定制实战
Naive UI Progress 进度条组件完整指南:类型、属性与定制实战
Naive UI 的 NProgress 进度条组件覆盖线性进度条、环形进度条、多环进度条与仪表盘四种形态,支持状态着色、渐变填充、自定义指示器与主题定制。本文基于仓库内组件文档(src/progress/demos/enUS/index.demo-entry.md)与源码实现,系统讲解其全部 Props、Slots、内置 Demo 用法与底层渲染机制,帮助你在 Vue 3 项目中快速落地并深度定制进度展示。
组件总览
NProgress 是 Naive UI 提供的数据展示组件,通过 type 属性在四种形态间切换:
type 取值 |
形态 | 适用场景 |
|---|---|---|
line |
线性进度条 | 任务下载、表单提交、批量处理等 |
circle |
单环进度 | 磁盘占用、技能评分、单一指标占比 |
multiple-circle |
多环进度 | 多指标对比、多维度占比展示 |
dashboard |
仪表盘 | 半圆仪表、绩效刻度(2.25.2 版本起支持) |
组件入口由 src/progress/index.ts 导出:NProgress 组件与 progressProps 属性集合、ProgressProps 类型声明;组件主体实现位于 src/progress/src/Progress.tsx,按 type 分发到三个子渲染组件:Line.tsx、Circle.tsx、MultipleCircle.tsx。从源码结构看,dashboard 与 circle 共用同一套圆形渲染管线,仅通过缺口角度(gap)与起始偏移区分。
<template>
<n-progress type="line" :percentage="50" />
<n-progress type="circle" :percentage="75" />
<n-progress type="dashboard" :percentage="80" />
<n-progress type="multiple-circle" :percentage="[80, 60, 40]" />
</template>
Progress Props 全参数详解
以下参数表完整继承自组件文档(src/progress/demos/enUS/index.demo-entry.md),并补充了源码(Progress.tsx)中的类型约束与默认值说明。
形态与几何尺寸
| Name | Type | Default | Description |
|---|---|---|---|
| type | 'line' | 'circle' | 'multiple-circle' | 'dashboard' |
line |
进度类型,'dashboard' 自 2.25.2 起可用。 |
| percentage | number | number[] |
0 |
进度百分比。circle/line/dashboard 传单个数值;multiple-circle 传数值数组,数组长度即环数。 |
| stroke-width | number |
7 |
圆形类进度的描边宽度(线宽)。 |
| height | number |
undefined |
'line' 型进度条高度;不传时使用主题默认高度(light 主题中 railHeight 为 8px,见 styles/light.ts)。 |
| view-box-width | number |
100 |
圆形类进度的 SVG viewBox 宽度(内部参数,文档 Demo 未直接暴露,源码默认 100)。 |
viewBoxWidth 是圆形类组件用于归一化绘制的坐标系宽度:circle-gap、gap-degree 等参数都以该坐标系为基准描述几何关系,默认值 100 意味着"按百分比想象一个 100×100 的虚拟画布"。
外观与颜色
| Name | Type | Default | Description |
|---|---|---|---|
| color | string | string[] | { stops: string[] } | Array<{ stops: string[] }> |
undefined |
进度填充色。{ stops: string[] } 表示线性渐变,stops 数组长度必须为 2,首元素为渐变起始色、末元素为渐变结束色;stops 形式自 2.40.2 起支持。 |
| rail-color | string | string[] |
undefined |
轨道(背景槽)颜色,默认取主题 progressRailColor。 |
| rail-style | string | CSS | Array<string | CSS> |
undefined |
轨道样式,可传 CSS 字符串、CSSProperties 对象或按环对应的数组,用于覆盖透明度等细节。 |
| indicator-text-color | string |
undefined |
指示器文本颜色,覆盖主题默认文本色。 |
| border-radius | number | string |
undefined |
'line' 型进度条整体的圆角;不传时保持默认高度一半的圆角。 |
| fill-border-radius | number | string |
undefined |
'line' 型进度条填充部分的圆角;不传时沿用 border-radius 值。 |
| unit | string |
% |
进度指示器的单位后缀。 |
指示器与状态
| Name | Type | Default | Description |
|---|---|---|---|
| show-indicator | boolean |
true |
是否显示百分比指示器。 |
| indicator-placement | 'inside' | 'outside' |
'outside' |
指示器位置('line' 型专用):外侧或进度条内部。 |
| indicator-text-color | string |
undefined |
指示器文本颜色。 |
| status | 'default' | 'success' | 'error' | 'warning' | 'info' |
'default' |
状态,决定默认填充色与指示图标配色。 |
| processing | boolean |
false |
处理中状态,仅在 'line' 型上叠加流动高光动画。 |
圆形专属参数
| Name | Type | Default | Description |
|---|---|---|---|
| circle-gap | number |
1 |
'multiple-circle' 各环之间的间隙,以 viewBox 尺寸(默认 100)为基准。 |
| gap-degree | number |
75 |
半圆仪表缺口角度,取值 0 ~ 360;对 dashboard 默认 75,2.25.2 起可用。 |
| gap-offset-degree | number |
0 |
缺口起始的偏移角度,用于旋转缺口位置,2.25.2 起可用。 |
| offset-degress | number |
0 |
环形进度起点的偏移角度(文档保留原拼写,语义即旋转起点),仅对 circle 型生效,2.24.0 起可用。 |
源码中 Progress.tsx 的 gapDeg 计算逻辑印证了默认值行为:dashboard 在未显式传 gap-degree 时取 75,circle 未传时取 0。
兼容性说明
文档属性表中还保留了 indicator-position('inside' \| 'outside',默认 'outside')。从源码看它作为 indicatorPlacement 的兼容别名存在:Progress.tsx 通过 mergedIndicatorPlacementRef 优先取 indicatorPlacement,未传时回退到 indicatorPosition,新代码推荐直接使用 indicator-placement。
状态与主题联动
status 驱动填充色与图标色的切换,默认颜色定义在主题文件中(src/progress/styles/light.ts):
| 状态 | 填充色 | 图标色 |
|---|---|---|
default / info |
infoColor |
infoColor |
success |
successColor |
successColor |
warning |
warningColor |
warningColor |
error |
errorColor |
errorColor |
Progress.tsx 通过 createKey('fillColor', status) 与 createKey('iconColor', status) 动态取用对应 CSS 变量,并统一注入 --n-fill-color、--n-rail-color 等主题变量;同时设置 aria-valuemax="100"、aria-valuemin="0"、aria-valuenow 与 role="progressbar"(circle/line/dashboard 类型),保证无障碍可访问性。
若需全量覆盖主题变量(如 fontSizeCircle、iconSizeLine、lineBgProcessing 等),可借助 Naive UI 主题覆盖机制,示例:
import { NConfigProvider, NProgress, darkTheme } from 'naive-ui'
import type { GlobalThemeOverrides } from 'naive-ui'
const themeOverrides: GlobalThemeOverrides = {
Progress: {
fontSizeCircle: '32px',
railColor: '#f0f0f0',
fillColorSuccess: '#18a058'
}
}
十一个内置 Demo 实战解读
文档声明区列出了全部 11 个示例,对应 src/progress/demos/enUS/ 目录下的同名 .vue 文件,逐一说明其核心用法。
1. Line —— 线性进度条基础
line.demo.vue 演示了 line 型在 default/info/success/warning/error 五种状态下的三种指示器形态:show-indicator=false(无指示器)、默认外侧指示器、indicator-placement="inside"(内部指示器)。示例通过 n-button 配合 +10/-10 动态增减 percentage 观察变化:
<n-progress type="line" :percentage="percentage" :show-indicator="false" />
<n-progress type="line" :percentage="percentage" />
<n-progress type="line" :percentage="percentage" indicator-placement="inside" />
<n-progress type="line" status="success" :percentage="percentage" />
2. Circle —— 环形进度条基础
circle.demo.vue 展示 circle 型在五种状态下的默认样式,一个组件即可满足绝大多数环形展示需求。
3. Circle offset —— 环形起点偏移
circle-offset.demo.vue 演示 offset-degree 的用法:offset-degree 按角度旋转环形进度的绘制起点,适合制作"起止点不在正上方"的特殊仪表效果:
<n-progress type="circle" :percentage="80" :offset-degree="120" />
4. Multiple circle —— 多环进度
multiple-circle.demo.vue 演示多环用法:percentage 传数组(环数与数组长度一致)、color 与 rail-style 传数组分别给每环上色,circle-gap 控制环间隙。示例通过 CSS 变量(var(--info-color) 等)让多环配色自动跟随主题:
<n-progress
type="multiple-circle"
:stroke-width="6"
:circle-gap="0.5"
:percentage="[percentage, (percentage + 10) % 100, (percentage + 20) % 100]"
:color="['var(--info-color)', 'var(--success-color)', 'var(--warning-color)']"
:rail-style="[
{ stroke: 'var(--info-color)', opacity: 0.3 },
{ stroke: 'var(--success-color)', opacity: 0.3 },
{ stroke: 'var(--warning-color)', opacity: 0.3 },
]"
/>
5. Dashboard —— 仪表盘
dashboard.demo.vue 演示仪表盘定制:gap-degree 控制缺口大小,gap-offset-degree 控制缺口位置。文档示例同时展示了 gap-position="bottom"(底部缺口,保留在 Demo 中)与显式传 gap-offset-degree="120"、gap-degree="120" 的两种写法:
<n-progress type="dashboard" gap-position="bottom" :percentage="80" />
<n-progress
type="dashboard"
:gap-offset-degree="120"
:gap-degree="120"
:percentage="80"
/>
6. Custom indicator —— 自定义指示器
custom-indicator.demo.vue 演示通过默认插槽完全替换指示器内容(详见下文 Slots 一节),环形与线性均适用:
<n-progress type="circle" :percentage="20">
<span style="text-align: center">20% is small</span>
</n-progress>
7. Color —— 自定义颜色
color.demo.vue 演示脱离内置状态色的做法:配合 useThemeVars() 取主题色、seemly 的 changeColor 生成带透明度的轨道色,实现"填充色 + 同色系轨道 + 指示器文本同色"的完整自定义配色:
<script lang="ts" setup>
import { useThemeVars } from 'naive-ui'
import { changeColor } from 'seemly'
const themeVars = useThemeVars()
</script>
<template>
<n-progress
type="circle"
:percentage="20"
:color="themeVars.successColor"
:rail-color="changeColor(themeVars.successColor, { alpha: 0.2 })"
:indicator-text-color="themeVars.successColor"
/>
</template>
8. No indicator —— 隐藏指示器
no-indicator.demo.vue 演示 show-indicator=false 在三种类型上的效果,适用于纯视觉进度表达(如加载封面、数据面板背景条)。
9. Height —— 高度与圆角
height.demo.vue 演示 line 型的高度与圆角定制:height 改高度、border-radius 改整体圆角、fill-border-radius 单独改填充段圆角。文档示例还展示了不规则圆角写法("12px 0 12px 0" 四值语法),并配合默认插槽在进度条内放置自定义内容:
<n-progress
type="line"
status="error"
:percentage="50"
:height="24"
border-radius="12px 0 12px 0"
fill-border-radius="12px 0 12px 0"
>
A Kind of Art
</n-progress>
10. Processing —— 处理中动画
processing.demo.vue 演示 processing 属性:为 line 型叠加一层流动高光。其视觉样式来自主题变量 lineBgProcessing(styles/light.ts 中定义为白色渐变线性渐变),适合"任务进行中"的实时进度反馈。
11. Gradient —— 线性渐变
gradient.demo.vue 演示 stops 渐变语法(2.40.2 起):传 { stops: [startColor, endColor] } 即可得到从起始色到结束色的线性渐变;multiple-circle 的 color 数组元素同样可以是渐变对象:
<n-progress type="line" :percentage="percentage" :color="{ stops: ['white', 'pink'] }" />
<n-progress type="circle" :percentage="percentage" :color="{ stops: ['#E3F2FD', '#2080f0'] }" />
Progress Slots
组件仅提供一个插槽,用于替换默认指示器内容:
| Name | Parameters | Description |
|---|---|---|
| default | () |
自定义内容将替换默认的指示器内容。 |
从 Progress.tsx 的渲染逻辑看,插槽会被透传到 Line、Circle、MultipleCircle 三个子组件内部,并出现在各自指示器位置(line 型会依据 indicator-placement 决定插槽渲染在内部还是外侧)。典型用法即上文"自定义指示器"与"高度与圆角"两个 Demo 中展示的写法。
源码级渲染原理
Progress.tsx 的渲染流程可归纳为:
- 外层容器统一挂载
n-progress、n-progress--{type}、n-progress--{status}三个类名,并将计算出的 CSS 变量作为内联样式注入; circle与dashboard走 Circle.tsx(SVG 环形),line走 Line.tsx,multiple-circle走 MultipleCircle.tsx;- 圆形类组件共享
strokeWidth、railStyle、color等参数,dashboard通过gapDeg计算逻辑(默认 75° 缺口)区别于circle; - 主题通过
useTheme('Progress', ...)挂载,样式定义在 src/progress/styles/index.cssr.ts,支持 light/dark 双主题(styles/light.ts、styles/dark.ts)与按需引入。
组件同时提供 ProgressProps(导出自 Progress.tsx)与 ProgressStatus、ProgressGradient 类型(src/progress/src/public-types.ts),供 TypeScript 项目做严格的类型推导。
测试覆盖与使用建议
仓库在 src/progress/tests/Progress.spec.ts 与 src/progress/tests/server.spec.tsx 中提供了组件测试(含服务端渲染场景),可参考其断言方式验证自定义配置的渲染结果。
实操建议速查:
- 动态数值:
percentage用ref驱动,配合n-button或定时器即可实现实时进度; - 状态优先:不需要特殊配色时直接用
status五态,保持与全局主题一致; - 多环配比:
multiple-circle的数组长度即环数,color/rail-color/rail-style数组按环一一对应; - 圆角细节:
line型追求"胶囊"观感时留空border-radius(默认取高度一半);需要直角时显式传0; - 仪表盘缺口:
gap-degree(0 ~ 360)控制缺口大小,gap-offset-degree控制缺口位置,组合可实现任意朝向的仪表盘; - 渐变:
{ stops: [start, end] }即可获得双色渐变,避免手写 SVG 渐变定义。
中文版文档入口位于 src/progress/demos/zhCN/index.demo-entry.md,与英文版参数表完全一致,可对照阅读。