progress-bar-cj API速查手册：MaterialModel、ComWheel全部接口一图看懂-平芜编程栈

progress-bar-cj API速查手册：MaterialModel、ComWheel全部接口一图看懂

【免费下载链接】progress-bar-cj自定义进度条归一化UI组件项目地址: https://gitcode.com/Cangjie-TPC/progress-bar-cj

progress-bar-cj是一个用仓颉语言编写的鸿蒙系统进度条 UI 组件三方库，提供 Material / Smooth 双风格、圆形 + 水平两种形态的自定义进度条。本文作为progress-bar-cj API 速查手册，带你一图看懂MaterialModel、ComMaterialModel、ComWheel三大核心类与MaterialProgressStyle枚举的全部接口，鸿蒙仓颉开发者收藏这一篇就够了。

📌 组件全景：4 种进度条形态，一个组件全搞定

MaterialProgressBar是库的"总入口"组件，构造时传入风格和配置模型两个参数，即可切换以下 4 种形态：

风格枚举	形态	适用场景
`MaterialCircular`	Material 圆形进度轮	加载状态、环形仪表
`MaterialHorizontal`	Material 水平进度柱	下载进度、任务进度
`SmoothCircular`	Smooth 圆形进度轮	平滑过渡动画效果
`SmoothHorizontal`	Smooth 水平进度柱	平滑过渡动画效果

枚举完整定义见 material_progress_style.cj。

🎨 MaterialModel：水平柱与 Material 圆形的"总控开关"

MaterialModel是MaterialProgressBar的配置模型类（带@Observed状态监听），源码见 material_progress_bar.cj。全部 setter 接口按功能分组如下：

颜色与背景

接口	参数类型	作用
`setColor`	UInt32	设置进度条主色
`setColors`	Array<UInt32>	设置多色数组（彩色进度条）
`setSecondColor`	UInt32	设置第二进度条颜色
`setBgColor`	UInt32	设置背景轨道颜色
`setShowProgressBackground`	Bool	一键显示/隐藏背景轨道
`setIsGradients`	Bool	开启渐变效果

进度与几何

接口	参数类型	作用
`setProgress`	Float64	设置主进度值（默认 30.0）
`setSecondProgress`	Float64	设置第二进度值
`setAngle`	Float64	设置角度
`setRadius`	Float64	设置圆形进度轮半径（默认 50.0）
`setStrokeWidth`	Float64	设置描边宽度（默认 8.0）

动画与特效

接口	参数类型	作用
`setIndeterminate`	Bool	开启"不确定模式"（无限滚动动画）
`setIndeterminateAngle`	Bool	开启不确定角度摆动效果
`setSpeed`	Float64	设置动画速度（默认 1.5）
`setCurve`	Curve	设置动画曲线（默认`Curve.Linear`）
`setIsStop`	Bool	停止动画
`setIsReversed`	Bool	反转方向
`setIsMirror`	Bool	镜像效果
`setIsPocket`	Bool	凹陷样式开关

分割与风格

接口	参数类型	作用
`setStyle`	MaterialProgressStyle	切换 4 种进度条形态
`setSeparatorLength`	Float64	设置分割段长度
`setSectionsCount`	Int64	设置分割次数（默认 4）
`setHorizontalLength`	Float64	设置水平柱长度
`setProgressInit`	Float64	设置初始进度值

🎡 ComMaterialModel + ComWheel：进度轮专属 API

想要"轮圈 + 旋转动画 + 百分比文字"的精致进度轮？用独立组件ComWheel，源码见 com_wheel.cj。它内部持有配置模型ComMaterialModel，接口分为三组：

外观设置

接口	参数类型	作用
`setCircleRadius`	Float64	进度轮半径（默认 30.0）
`setBarColor`	UInt32	画笔（进度弧）颜色
`setRimColor`	UInt32	外轮圈颜色
`setBarWidth`	Float64	进度弧宽度（默认 5.0）
`setRimWidth`	Float64	轮圈宽度（默认 5.0）
`setSpinSpeed`	Float64	旋转速度（默认 230.0）

进度控制

接口	参数类型	作用
`setProgress`	Float64	设置目标进度（0.0 ~ 1.0，带缓动动画）
`setInstantProgress`	Float64	立即跳到指定进度（无动画）
`setLinearProgress`	Bool	切换线性/缓动插值模式
`getProgress`	-	获取当前进度文本
`resetCount`	-	进度清零

旋转控制

接口	参数类型	作用
`setSpinning`	Bool	开启/关闭旋转动画
`spin`	-	启动旋转
`stopSpinning`	-	停止旋转并清零
`spinning`	-	查询是否正在旋转
`init_data`	-	初始化轮圈路径与动画定时器
`closeTimer`	-	取消动画定时器（组件销毁时自动调用）

🔗 其他通用类：一眼扫完

类	位置	说明
`MaterialProgressBar`	material_progress_bar.cj	总入口组件，按 style 自动分发 4 个子组件
`MaterialProgressStyle`	material_progress_style.cj	4 种风格枚举，支持`==`/`!=`比较
`ProgressBar`接口	progress_bar.cj	定义`setProgress`/`getProgress`/`setMaxProgress`/`getMaxProgress`四个契约方法
`CircularComponent`	circular_component.cj	圆形进度属性载体：`bgColor`、`color`、`strokeWidth`、`progress`、`progressMax`、`angle`等字段
`HorizontalComponent`	horizontal_component.cj	水平进度属性载体，字段与圆形一致并增加偏移量`mOffset`

🛠 快速上手：三步接入进度条组件

引入依赖：将progressbar模块拷贝到工程，在oh-package.json5的 dependencies 中添加"progressbar": "file:../progressbar"，并在cjpm.toml中配置路径依赖（详细步骤见 README.md）。
导入包：在页面文件中import progressbar.*。
配置并声明组件：在aboutToAppear中配置MaterialModel，在build中声明组件。最小示例：

var frameworkModel: MaterialModel = MaterialModel() this.frameworkModel.setStyle(MaterialProgressStyle.MaterialHorizontal) this.frameworkModel.setProgress(30.0) this.frameworkModel.setColor(0x009688) // build 中声明 MaterialProgressBar(style: MaterialProgressStyle.MaterialHorizontal, modelBuild: this.frameworkModel)

完整可运行示例见 material_progress_bar_sample.cj，其中演示了彩色进度、Tinted 染色、不确定模式、工具栏进度条等多种玩法。