n-progress 进度条
展示操作或任务的当前进度（上传 / 下载 / 任务完成度）：轨道 + 进度条横向铺满容器，percent 驱动进度动画（每变动 1% 所需毫秒数可调，0 关动画直接到位），动画到位派发 activeend。右侧可显示百分比文字（text 插槽整位替换），左侧 label 插槽放引导词。进度色支持实色与 linear-gradient 渐变（方向须用关键词形式），形状 pill / square 两档，轨道色默认跟随主题深浅。
- 零配置即用：
<n-progress :percent="40" />出一条品牌色胶囊进度条，铺满父容器- 进度动画：
percent变化从当前显示值续播到新目标（挂载从 0 起步入场），duration调速、0 关动画；到位派发activeend（参数为到达值）- 文字与插槽：
show-text开右侧百分比文字（动画中数字随条滚动），text插槽整位替换（如 "12 MB / 20 MB"），label插槽放左侧引导词
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
如何调用
html
<n-progress :percent="40" />API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| percent | number | 0 | 进度百分比 0~100，越界自动夹取到边界；支持小数（如 66.6，到位后文字按原值显示） |
| strokeWidth | number | 8 | 进度条高度（px） |
| color | string | "" | 已选进度条颜色；空 = 品牌色（跟随 --n-color-primary）。渐变须用关键词方向，如 "linear-gradient(to right, #10b981, #6366f1)" |
| inactiveColor | string | "" | 轨道颜色；空 = 次级表面色（跟随主题深浅自动）；transparent 关闭轨道底色（纯进度条形态） |
| showText | boolean | false | 右侧显示百分比文字；提供 text 插槽时显示插槽内容（替换内置百分比文本） |
| textPosition | string | "right" | 百分比文字位置：right 右侧独立文字位（默认）/ inside 悬浮在轨道上居中（双层叠字：填充段白色、未填充段墨色，对比色自动分割） |
| textSize | number | 14 | 百分比文字字号（px）；inside 位置为字号上限——超出条高可容时自动收缩（字号 ≤ 1.4×条高 − 2），字身永不出胶囊 |
| textColor | string | "" | 百分比文字颜色；空 = 主题墨色（深浅自动） |
| shape | string | "pill" | 进度条形状：pill 胶囊（两端全圆角，随高度自适应）/ square 直角 |
| duration | number | 15 | 进度动画速度：进度每变动 1% 所需毫秒数；0 = 关闭动画（直接到位） |
| textStyle | string | "" | 百分比文字行内样式（如 "font-weight:600"）；仅对内置百分比文本生效 |
| customClass | string | "" | 挂到根节点的额外 class（类需定义在组件样式表内） |
| customStyle | string | "" | 根节点行内样式：排间距（如 "margin:10px 0"）走它 |
事件
| 事件名 | 说明 |
|---|---|
| activeend | 进度到达目标值时触发（含挂载到位与无动画直达到位），参数为到达的百分比数值 |
插槽
| 插槽名 | 说明 |
|---|---|
| label | 左侧引导词位（如「上传中」「加载进度」）；插槽静态提供，内容自适应宽 |
| text | 文字位，整位替换内置百分比文本（如 "9 MB / 20 MB"）；仅 showText 开启时渲染；textPosition=inside 时悬浮轨道居中（单层，对比色由内容自理） |
主题令牌
| 令牌 | 默认值 | 说明 |
|---|---|---|
| --n-progress-color | var(--n-color-primary) | 已选进度条颜色（缺省挂全局品牌色，深浅不变） |
| --n-progress-track-color | var(--n-bg-2) | 轨道颜色（缺省挂全局表面色，深浅主题自动） |
| --n-progress-text-gap | 8px | 轨道与右侧百分比文字 / 左侧引导词的间距 |
| --n-progress-radius-pill | 999px | pill 胶囊形态圆角 |
| --n-progress-radius-square | 0px | square 直角形态圆角（需要微圆角可覆盖此令牌） |
实现说明
与参考实现对照的取舍（同类组件功能面取并集、冲突从使用者视角择优融合）
| 机制 | 参考做法 | 本库做法 | 分歧理由 |
|---|---|---|---|
| 值域模型 | percent 0~100 越界夹取（各参考一致） | 相同 | 一致 |
| 进度动画 | CSS transition 驱动 transform 位移 / width（时长固定或每 1% 毫秒） | JS 帧循环逐帧写行内 width（30ms 一帧线性，时长 = |目标 - 当前| × duration） | 库动画规范统一帧循环（n-loading / n-button 同构链路）；CSS 过渡与 @keyframes 链路不走；时长语义取「每 1% 毫秒」（与原生 / 同类一致） |
| 大幅回落 | 回落超 30 时动画时间减半 | 相同 | 回落是状态重置而非进度推进，全速拖完观感迟滞 |
| 动画结束事件 | activeend 空参数 / 携带当前值两种 | 携带到达的百分比数值 | 参数超集，语义不变 |
| 渐变进度色 | 行内 background 简写直写 | 承接类 + 行内变量双轨（实色 background-color / 渐变 background-image），色种类切换整行销毁重建 | App 端行内 background 简写被编译器拒绝、background 动态改值有不重绘官方已知 Bug（库内验证过的可靠链路） |
| 形状 | 任意 radius 数值 prop | shape 两档（pill / square）+ 令牌（square 缺省直角，微圆角经令牌覆盖） | 库内形状通道惯例；pill 即「圆角 = 高度一半」随 strokeWidth 自适应，任意值经令牌覆盖 |
| 百分比文字 | 固定宽文字盒（防数字增减抖动） | 内容自适应 + 不收缩（数字宽度变化由轨道 flex:1 吸收） | 固定宽在 text 插槽自定义内容下会裁内容；flex 收缩同样消除抖动 |
| 文字数值 | 显示目标百分比 | 动画中显示插值整值（数字随条滚动），到位后显示精确目标值（支持小数原样显示） | 兼得滚动观感与精确表达 |
| 挂载动画 | 挂载从 0 动画到值（多数参考） | 相同 | 入场自带进度感；duration=0 可关 |
| 条内悬浮文字 | 各参考线性组件均无此形态（参考源中心悬浮数值属环形组件）；同类库 inside 文字固定字号、条高不足即溢出 | textPosition=inside 双层叠字：底层墨色全幅 + 顶层白字按进度裁剪，填充边界自动分割对比色（轨道宽实测 + 窗口/结构变化重测）；字号自动收缩不出胶囊（字号 ≤ 1.4×条高 − 2） | 确认的扩展需求：居中悬浮在低进度时单色不可兼顾深浅底，双层叠字全态可读；小条高下文字溢出属参考源同类缺陷，本库以自动收缩根治 |
| 不收项 | 原生 active / active-mode（动画从头播 / 续播模式开关） | 恒从当前显示值向目标续播 | 挂载从 0 起步已覆盖「从头播」需求，模式开关是实现细节；受控值驱动的过渡天然是续播语义 |