Naive UI Progress 进度条组件完整指南:类型、属性与定制实战

原创2026-09-20 15:50:341,648 阅读
文章标签:前端UI组件设计系统

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 的渲染流程可归纳为:

  1. 外层容器统一挂载 n-progress、n-progress--{type}、n-progress--{status} 三个类名,并将计算出的 CSS 变量作为内联样式注入;
  2. circle 与 dashboard 走 Circle.tsx(SVG 环形),line 走 Line.tsx,multiple-circle 走 MultipleCircle.tsx;
  3. 圆形类组件共享 strokeWidth、railStyle、color 等参数,dashboard 通过 gapDeg 计算逻辑(默认 75° 缺口)区别于 circle;
  4. 主题通过 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,与英文版参数表完全一致,可对照阅读。

登录后查看全文
naive-ui