amis Progress 进度条组件完全指南从颜色映射到事件动作的 JSON 配置实战【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis进度条Progress是 amis 前端低代码框架内置的展示型组件通过一段 JSON Schema 即可渲染条形、圆形、仪表盘三种形态的进度效果并支持颜色映射、阈值刻度、条纹动画、字段联动与事件动作等能力。本文以官方文档 progress.md 为主体结合 Progress 渲染器源码、amis-ui 底层实现 与 单元测试完整讲解该组件的全部配置项、底层取值与配色原理以及作为 Field 嵌入 Table、Card、表单静态展示的实战用法读完即可在页面 JSON 中直接落地使用。一、基本用法progress组件最核心的属性只有两个type: progress与value进度值。一个最小可用的页面配置如下{ type: page, body: { type: progress, value: 60 } }在 amis 架构中该组件由两层协作完成渲染器层packages/amis/src/renderers/Progress.tsx中的ProgressField通过Renderer({type: progress})注册为 amis 渲染器负责取值、模板过滤、状态维护与动作分发表现层底层复用amis-ui的Progress组件packages/amis-ui/src/components/Progress.tsx负责条形/环形/仪表盘的实际绘制。取值逻辑见 Progress.tsx会先走getPropValue读取若拿到的是模板字符串再经filter按当前数据域渲染最终把形如60的字符串parseFloat为数字。因此value既可以直接写数字也可以写${xxx}之类的模板表达式动态跟随数据变化。二、颜色映射 map三种配置形态与底层分段原理map属性用于按进度值切换进度条颜色官方文档给出三种写法amis-ui中用联合类型ColorMapType Arraystring | ArrayColorProps | string约束见 Progress.tsx。1. 单个颜色字符串配置为单一颜色值如#F96D3E时整个进度条固定为该颜色{ type: page, body: { type: progress, value: 40, map: #F96D3E } }2. 字符串数组按等分区间切换 CSS 类默认的map配置为[bg-danger, bg-warning, bg-info, bg-success, bg-success]它意味着将进度条平均分成 5 份前 20% 添加bg-dangerCSS 类名20%~40% 添加bg-warning40%~60% 添加bg-info60%~80% 与 80%~100% 均添加bg-success。该规则在底层getColorArrayProgress.tsx中实现span 100 / color.length第index个元素的分段阈值为(index 1) * span即 20%、40%、60%、80%、100%。因此配置两个元素[bg-danger, bg-success]时即按 50% 为界切换完全由数组长度决定分段粒度。{ type: page, body: { type: progress, value: 60, map: [bg-danger, bg-success] } }说明默认值在 ProgressField.defaultProps 中定义。当完全不配置map时底层getCurrentColor会回退到bg-primary见 Progress.tsx。3. 对象数组精确控制每个区间当需要精确控制多少进度显示什么颜色时使用{value, color}对象数组。例如{ type: progress, value: 20, map: [{ value: 30, color: #007bff }, { value: 60, color: #fad733 }], mode: circle }语义为value小于等于 30 的区间显示#007bff大于 30 则显示#fad733。底层getLevelColorProgress.tsx会先把数组按value升序排序然后返回第一个阈值大于等于当前进度的颜色若当前进度超过所有阈值则取数组中最后一个颜色。源码对颜色字符串有个关键判断isColorClass /bg-/.test(bgColor)见 Progress.tsx。命中bg-*时按 CSS 类名挂载条形走bar的 className环形走rc-progress的prefixCls对应_progress.scss中的.bg-warning-circle-path等 stroke 规则否则视为真实颜色值直接写入backgroundColor条形或strokeColor环形。单元测试 Progress.test.tsx 完整验证了两种写法的渲染结果。三、阈值刻度threshold 与 showThresholdTextthreshold用于在条形进度条上绘制刻度线帮助用户直观判断当前进度处于哪个节点。配置格式为单个对象或对象数组其中value、color均支持模板{ type: page, body: { type: progress, value: 60, threshold: [ { value: 30%, color: red }, { value: 90%, color: blue } ], showThresholdText: true } }从实现看amis 渲染器在传入底层前会先对阈值做模板解析见 Progress.tsxvalue与color为字符串时经filter按当前数据域渲染从而支持${xxx}%这种动态刻度。底层渲染时Progress.tsx将value统一parseFloat后拼上%以绝对定位的竖线border-left落在进度条相应位置刻度线颜色默认取var(--text-color)showThresholdText: true时在刻度线下方bottom: -20px展示刻度文本相关样式见 _progress.scss。四、用作 FieldTable 列、List/Card 内容与表单静态展示Progress 不只能独立渲染还可以作为字段组件嵌入数据展示容器用于 Table 的列配置 Column、List 的内容、Card 卡片的内容以及表单的静态展示中。此时只需设置name属性组件即会从当前数据域中映射同名变量的值。Table 中的列类型{ type: table, data: { items: [ { id: 1, progress: 20 }, { id: 2, progress: 40 }, { id: 3, progress: 60 } ] }, columns: [ { name: id, label: Id }, { name: progress, label: 进度, type: progress } ] }List 的内容、Card 卡片的内容配置方式与上述 Table 列完全一致即{ name: progress, type: progress }。Form 中静态展示在表单内做只读展示时使用static-progress类型{ type: form, data: { progress: 60 }, body: [ { type: static-progress, name: progress, label: 进度 } ] }组件之所以能同时以progress与static-progress两种形态工作依赖 amis 的兼容层映射见 compat.ts其中progress: static-progress将普通展示组件自动转换为表单静态组件。同时amis 渲染器会监听name、value、data、defaultValue四个键的变化并刷新值COMPARE_KEYS见 Progress.tsx因此数据更新后进度会随之联动。五、显示背景间隔 stripe 与动画 animatestripe: true让条形进度条显示斜向条纹背景animate: true则启用动态效果。两者可以独立使用也可以组合出条纹滚动的效果。{ type: page, body: [ { type: progress, animate: true, value: 60 }, { type: divider }, { type: progress, animate: true, value: 60, stripe: true } ] }注意动画只在条形进度条mode为line下生效。从底层实现看Progress.tsxstripe/animate只作用于 line 分支的bar节点环形与仪表盘走rc-progress的Circle分支不参与这两项。样式层面对应三类修饰类见 _progress.scss.Progress-line-bar--stripe45 度线性渐变斜纹.Progress-line-bar--animateprogress-bar-active动画2.4s 流光扫过效果cubic-bezier 缓动无限循环.Progress-line-bar--stripe-animateprogress-bar-stripes动画1s 线性平移让斜纹滚动起来。因此 条纹 动画 会得到斜纹持续滚动的经典加载态效果而单独animate则是高光扫过的流光效果。六、圆形进度条与仪表盘进度条圆形进度条通过mode: circle切换为环形{ type: page, body: { type: progress, value: 60, mode: circle } }仪表盘进度条mode: dashboard渲染为缺口的仪表盘形态可通过gapDegree设置缺口角度、gapPosition设置缺口位置{ type: page, body: { type: progress, value: 60, mode: dashboard, gapDegree: 22, gapPosition: bottom } }底层实现Progress.tsx对两者统一处理环形/仪表盘基于rc-progress的Circle组件绘制percent即进度值gapPosition缺省时仪表盘默认取bottom普通圆形默认取topgapDegree缺省时仪表盘默认取75且可传0显式闭合容器尺寸由strokeWidth决定宽高均为strokeWidth * 10px未配置时线宽取8。七、设置线条宽度 strokeWidthstrokeWidth同时控制进度条线宽与环形/仪表盘模式的整体尺寸。条形模式直接把它作为进度条高度barStyle.height环形模式则作为描边宽度并参与容器尺寸计算。官方属性表标注line类型默认10circle、dashboard类型默认6需要指出的是底层 UI 组件在未传值时实际按strokeWidth || 8兜底以实际渲染为准。{ type: page, body: [ { type: progress, value: 60, mode: line, strokeWidth: 4 }, { type: progress, value: 60, mode: line, strokeWidth: 8 }, { type: progress, value: 60, mode: line, strokeWidth: 12 }, { type: progress, value: 60, mode: dashboard, strokeWidth: 4 }, { type: progress, value: 60, mode: dashboard, strokeWidth: 8 }, { type: progress, value: 60, mode: dashboard, strokeWidth: 12 } ] }八、自定义格式输出内容 valueTpl默认情况下进度文本展示为60%由默认值${value}%决定。通过valueTpl可自定义文本格式模板语法与 amis 通用的模板渲染一致内置变量value即当前进度值{ type: page, body: { type: progress, mode: circle, value: 60, valueTpl: ${value}个 } }实现上Progress.tsxformat方法用createObject(data, {value})把当前值注入数据域再以valueTpl作为模板渲染因此valueTpl里还可以引用页面上的其他变量例如${value}/${total}。另外若设showLabel: false可完全隐藏进度文本底层getLabel返回 null当值为非数字如未取到数据时条形模式会展示占位文本placeholder默认-环形模式则不渲染内容相关逻辑见 Progress.tsx。九、属性表属性名类型默认值说明typestring如果在 Form 中用作静态展示为static-progressmodestringline进度「条」的类型可选line circle dashboardclassNamestring外层 CSS 类名value模板进度值placeholderstring-占位文本showLabelbooleantrue是否展示进度文本stripebooleanfalse背景是否显示条纹animatebooleanfalsetype 为 line可支持动画mapstring \| Arraystring \| Array{value:number, color:string}[bg-danger, bg-warning, bg-info, bg-success, bg-success]进度颜色映射threshold{value:模板, color?:模板} | Array{value:模板, color?:模板}-阈值刻度showThresholdTextbooleanfalse是否显示阈值刻度数值valueTplstring${value}%自定义格式化内容strokeWidthnumberline 类型为10circle、dashboard 类型为6进度条线宽度gapDegreenumber75仪表盘缺角角度可取值 0 ~ 295gapPositionstringbottom仪表盘进度条缺口位置可选top bottom left right十、事件动作reset 与 setValueProgress 对外暴露两个特性动作其他组件可通过actionType: 动作名称、componentId: 该组件 id触发并通过args传参。完整的事件动作机制见事件动作文档。动作名称动作配置说明reset-将值重置为 0setValuevalue: string|number更新的值更新数据这两个动作在 ProgressFieldRenderer 中实现doAction捕获reset并将内部value置 0setData负责数值类型转换后更新状态配合渲染器在ScopedContext中的注册/注销机制使组件可被componentId精准寻址。reset 示例{ type: page, body: [ { type: progress, name: progress, id: progress, value: 67 }, { type: button, label: 重置值, onEvent: { click: { actions: [ { actionType: reset, componentId: progress } ] } } } ] }setValue 示例{ type: page, body: [ { type: progress, name: progress, id: progress, value: 67 }, { type: button, label: 设置值, onEvent: { click: { actions: [ { actionType: setValue, componentId: progress, args: { value: 20 } } ] } } } ] }小结Progress 组件的能力清单可以概括为三种形态line / circle / dashboard、三类配色映射单色 / 等分数组 / 对象区间、两套刻度与动效threshold 阈值、stripe 条纹 animate 动画、一个模板出口valueTpl与两个动作入口reset / setValue。从源码看取值、模板解析、颜色分段、动画类切换各司其职单元测试 Progress.test.tsx 对上述能力逐项覆盖。在实际项目中进度条常与 Table、Card、List 等数据展示组件组合实现数据即进度的动态展示效果。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
amis Progress 进度条组件完全指南：从颜色映射到事件动作的 JSON 配置实战
amis Progress 进度条组件完全指南从颜色映射到事件动作的 JSON 配置实战【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis进度条Progress是 amis 前端低代码框架内置的展示型组件通过一段 JSON Schema 即可渲染条形、圆形、仪表盘三种形态的进度效果并支持颜色映射、阈值刻度、条纹动画、字段联动与事件动作等能力。本文以官方文档 progress.md 为主体结合 Progress 渲染器源码、amis-ui 底层实现 与 单元测试完整讲解该组件的全部配置项、底层取值与配色原理以及作为 Field 嵌入 Table、Card、表单静态展示的实战用法读完即可在页面 JSON 中直接落地使用。一、基本用法progress组件最核心的属性只有两个type: progress与value进度值。一个最小可用的页面配置如下{ type: page, body: { type: progress, value: 60 } }在 amis 架构中该组件由两层协作完成渲染器层packages/amis/src/renderers/Progress.tsx中的ProgressField通过Renderer({type: progress})注册为 amis 渲染器负责取值、模板过滤、状态维护与动作分发表现层底层复用amis-ui的Progress组件packages/amis-ui/src/components/Progress.tsx负责条形/环形/仪表盘的实际绘制。取值逻辑见 Progress.tsx会先走getPropValue读取若拿到的是模板字符串再经filter按当前数据域渲染最终把形如60的字符串parseFloat为数字。因此value既可以直接写数字也可以写${xxx}之类的模板表达式动态跟随数据变化。二、颜色映射 map三种配置形态与底层分段原理map属性用于按进度值切换进度条颜色官方文档给出三种写法amis-ui中用联合类型ColorMapType Arraystring | ArrayColorProps | string约束见 Progress.tsx。1. 单个颜色字符串配置为单一颜色值如#F96D3E时整个进度条固定为该颜色{ type: page, body: { type: progress, value: 40, map: #F96D3E } }2. 字符串数组按等分区间切换 CSS 类默认的map配置为[bg-danger, bg-warning, bg-info, bg-success, bg-success]它意味着将进度条平均分成 5 份前 20% 添加bg-dangerCSS 类名20%~40% 添加bg-warning40%~60% 添加bg-info60%~80% 与 80%~100% 均添加bg-success。该规则在底层getColorArrayProgress.tsx中实现span 100 / color.length第index个元素的分段阈值为(index 1) * span即 20%、40%、60%、80%、100%。因此配置两个元素[bg-danger, bg-success]时即按 50% 为界切换完全由数组长度决定分段粒度。{ type: page, body: { type: progress, value: 60, map: [bg-danger, bg-success] } }说明默认值在 ProgressField.defaultProps 中定义。当完全不配置map时底层getCurrentColor会回退到bg-primary见 Progress.tsx。3. 对象数组精确控制每个区间当需要精确控制多少进度显示什么颜色时使用{value, color}对象数组。例如{ type: progress, value: 20, map: [{ value: 30, color: #007bff }, { value: 60, color: #fad733 }], mode: circle }语义为value小于等于 30 的区间显示#007bff大于 30 则显示#fad733。底层getLevelColorProgress.tsx会先把数组按value升序排序然后返回第一个阈值大于等于当前进度的颜色若当前进度超过所有阈值则取数组中最后一个颜色。源码对颜色字符串有个关键判断isColorClass /bg-/.test(bgColor)见 Progress.tsx。命中bg-*时按 CSS 类名挂载条形走bar的 className环形走rc-progress的prefixCls对应_progress.scss中的.bg-warning-circle-path等 stroke 规则否则视为真实颜色值直接写入backgroundColor条形或strokeColor环形。单元测试 Progress.test.tsx 完整验证了两种写法的渲染结果。三、阈值刻度threshold 与 showThresholdTextthreshold用于在条形进度条上绘制刻度线帮助用户直观判断当前进度处于哪个节点。配置格式为单个对象或对象数组其中value、color均支持模板{ type: page, body: { type: progress, value: 60, threshold: [ { value: 30%, color: red }, { value: 90%, color: blue } ], showThresholdText: true } }从实现看amis 渲染器在传入底层前会先对阈值做模板解析见 Progress.tsxvalue与color为字符串时经filter按当前数据域渲染从而支持${xxx}%这种动态刻度。底层渲染时Progress.tsx将value统一parseFloat后拼上%以绝对定位的竖线border-left落在进度条相应位置刻度线颜色默认取var(--text-color)showThresholdText: true时在刻度线下方bottom: -20px展示刻度文本相关样式见 _progress.scss。四、用作 FieldTable 列、List/Card 内容与表单静态展示Progress 不只能独立渲染还可以作为字段组件嵌入数据展示容器用于 Table 的列配置 Column、List 的内容、Card 卡片的内容以及表单的静态展示中。此时只需设置name属性组件即会从当前数据域中映射同名变量的值。Table 中的列类型{ type: table, data: { items: [ { id: 1, progress: 20 }, { id: 2, progress: 40 }, { id: 3, progress: 60 } ] }, columns: [ { name: id, label: Id }, { name: progress, label: 进度, type: progress } ] }List 的内容、Card 卡片的内容配置方式与上述 Table 列完全一致即{ name: progress, type: progress }。Form 中静态展示在表单内做只读展示时使用static-progress类型{ type: form, data: { progress: 60 }, body: [ { type: static-progress, name: progress, label: 进度 } ] }组件之所以能同时以progress与static-progress两种形态工作依赖 amis 的兼容层映射见 compat.ts其中progress: static-progress将普通展示组件自动转换为表单静态组件。同时amis 渲染器会监听name、value、data、defaultValue四个键的变化并刷新值COMPARE_KEYS见 Progress.tsx因此数据更新后进度会随之联动。五、显示背景间隔 stripe 与动画 animatestripe: true让条形进度条显示斜向条纹背景animate: true则启用动态效果。两者可以独立使用也可以组合出条纹滚动的效果。{ type: page, body: [ { type: progress, animate: true, value: 60 }, { type: divider }, { type: progress, animate: true, value: 60, stripe: true } ] }注意动画只在条形进度条mode为line下生效。从底层实现看Progress.tsxstripe/animate只作用于 line 分支的bar节点环形与仪表盘走rc-progress的Circle分支不参与这两项。样式层面对应三类修饰类见 _progress.scss.Progress-line-bar--stripe45 度线性渐变斜纹.Progress-line-bar--animateprogress-bar-active动画2.4s 流光扫过效果cubic-bezier 缓动无限循环.Progress-line-bar--stripe-animateprogress-bar-stripes动画1s 线性平移让斜纹滚动起来。因此 条纹 动画 会得到斜纹持续滚动的经典加载态效果而单独animate则是高光扫过的流光效果。六、圆形进度条与仪表盘进度条圆形进度条通过mode: circle切换为环形{ type: page, body: { type: progress, value: 60, mode: circle } }仪表盘进度条mode: dashboard渲染为缺口的仪表盘形态可通过gapDegree设置缺口角度、gapPosition设置缺口位置{ type: page, body: { type: progress, value: 60, mode: dashboard, gapDegree: 22, gapPosition: bottom } }底层实现Progress.tsx对两者统一处理环形/仪表盘基于rc-progress的Circle组件绘制percent即进度值gapPosition缺省时仪表盘默认取bottom普通圆形默认取topgapDegree缺省时仪表盘默认取75且可传0显式闭合容器尺寸由strokeWidth决定宽高均为strokeWidth * 10px未配置时线宽取8。七、设置线条宽度 strokeWidthstrokeWidth同时控制进度条线宽与环形/仪表盘模式的整体尺寸。条形模式直接把它作为进度条高度barStyle.height环形模式则作为描边宽度并参与容器尺寸计算。官方属性表标注line类型默认10circle、dashboard类型默认6需要指出的是底层 UI 组件在未传值时实际按strokeWidth || 8兜底以实际渲染为准。{ type: page, body: [ { type: progress, value: 60, mode: line, strokeWidth: 4 }, { type: progress, value: 60, mode: line, strokeWidth: 8 }, { type: progress, value: 60, mode: line, strokeWidth: 12 }, { type: progress, value: 60, mode: dashboard, strokeWidth: 4 }, { type: progress, value: 60, mode: dashboard, strokeWidth: 8 }, { type: progress, value: 60, mode: dashboard, strokeWidth: 12 } ] }八、自定义格式输出内容 valueTpl默认情况下进度文本展示为60%由默认值${value}%决定。通过valueTpl可自定义文本格式模板语法与 amis 通用的模板渲染一致内置变量value即当前进度值{ type: page, body: { type: progress, mode: circle, value: 60, valueTpl: ${value}个 } }实现上Progress.tsxformat方法用createObject(data, {value})把当前值注入数据域再以valueTpl作为模板渲染因此valueTpl里还可以引用页面上的其他变量例如${value}/${total}。另外若设showLabel: false可完全隐藏进度文本底层getLabel返回 null当值为非数字如未取到数据时条形模式会展示占位文本placeholder默认-环形模式则不渲染内容相关逻辑见 Progress.tsx。九、属性表属性名类型默认值说明typestring如果在 Form 中用作静态展示为static-progressmodestringline进度「条」的类型可选line circle dashboardclassNamestring外层 CSS 类名value模板进度值placeholderstring-占位文本showLabelbooleantrue是否展示进度文本stripebooleanfalse背景是否显示条纹animatebooleanfalsetype 为 line可支持动画mapstring \| Arraystring \| Array{value:number, color:string}[bg-danger, bg-warning, bg-info, bg-success, bg-success]进度颜色映射threshold{value:模板, color?:模板} | Array{value:模板, color?:模板}-阈值刻度showThresholdTextbooleanfalse是否显示阈值刻度数值valueTplstring${value}%自定义格式化内容strokeWidthnumberline 类型为10circle、dashboard 类型为6进度条线宽度gapDegreenumber75仪表盘缺角角度可取值 0 ~ 295gapPositionstringbottom仪表盘进度条缺口位置可选top bottom left right十、事件动作reset 与 setValueProgress 对外暴露两个特性动作其他组件可通过actionType: 动作名称、componentId: 该组件 id触发并通过args传参。完整的事件动作机制见事件动作文档。动作名称动作配置说明reset-将值重置为 0setValuevalue: string|number更新的值更新数据这两个动作在 ProgressFieldRenderer 中实现doAction捕获reset并将内部value置 0setData负责数值类型转换后更新状态配合渲染器在ScopedContext中的注册/注销机制使组件可被componentId精准寻址。reset 示例{ type: page, body: [ { type: progress, name: progress, id: progress, value: 67 }, { type: button, label: 重置值, onEvent: { click: { actions: [ { actionType: reset, componentId: progress } ] } } } ] }setValue 示例{ type: page, body: [ { type: progress, name: progress, id: progress, value: 67 }, { type: button, label: 设置值, onEvent: { click: { actions: [ { actionType: setValue, componentId: progress, args: { value: 20 } } ] } } } ] }小结Progress 组件的能力清单可以概括为三种形态line / circle / dashboard、三类配色映射单色 / 等分数组 / 对象区间、两套刻度与动效threshold 阈值、stripe 条纹 animate 动画、一个模板出口valueTpl与两个动作入口reset / setValue。从源码看取值、模板解析、颜色分段、动画类切换各司其职单元测试 Progress.test.tsx 对上述能力逐项覆盖。在实际项目中进度条常与 Table、Card、List 等数据展示组件组合实现数据即进度的动态展示效果。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考