HarmonyOS 6 Progress组件设置定制内容区使用文档

功能概述

contentModifier是 HarmonyOS 6 Progress 组件提供的内容定制接口，用于完全自定义进度条内部展示区域。
可通过该接口替换进度条默认显示内容，实现：

• 自定义文本展示
• 自定义图标/图形
• 进度联动的动态样式
• 多元素组合布局

核心 API

1. 接口定义

contentModifier(modifier:ContentModifier<ProgressConfiguration>):Progress

2. 关键类型

• ContentModifier：内容修饰器基类，用于定义自定义内容
• ProgressConfiguration：进度条配置信息，包含：
  • value：当前进度值
  • total：总进度值
  • enabled：进度条是否可用
  • contentModifier：绑定的修饰器实例

完整示例

// xxx.ets class MyProgressModifier implements ContentModifier<ProgressConfiguration> { color: ResourceColor = Color.White; constructor(color: ResourceColor) { this.color = color; } applyContent(): WrappedBuilder<[ProgressConfiguration]> { return wrapBuilder(myProgress); } } @Builder function myProgress(config: ProgressConfiguration) { Column({ space: 30 }) { Text('当前进度：' + config.value + '/' + config.total).fontSize(20) Row() { Flex({ justifyContent: FlexAlign.SpaceBetween }) { Path() .width('30%') .height('30%') .commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z') .fill(config.enabled && config.value >= 1 ? (config.contentModifier as MyProgressModifier).color : Color.White) .stroke(Color.Black) .strokeWidth(3) Path() .width('30%') .height('30%') .commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z') .fill(config.enabled && config.value >= 2 ? (config.contentModifier as MyProgressModifier).color : Color.White) .stroke(Color.Black) .strokeWidth(3) Path() .width('30%') .height('30%') .commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z') .fill(config.enabled && config.value >= 3 ? (config.contentModifier as MyProgressModifier).color : Color.White) .stroke(Color.Black) .strokeWidth(3) }.width('100%') } }.margin({ bottom: 100 }) } @Entry @Component struct Index { @State currentValue: number = 0; modifier = new MyProgressModifier('rgb(39, 135, 217)'); @State myModifier: (MyProgressModifier | undefined) = this.modifier; build() { Column() { Progress({ value: this.currentValue, total: 3, type: ProgressType.Ring }).contentModifier(this.modifier) Button('Progress++').onClick(() => { if (this.currentValue < 3) { this.currentValue += 1; } }).width('30%') Button('Progress--').onClick(() => { if (this.currentValue > 0) { this.currentValue -= 1; } }).width('30%').margin('10') }.width('100%').height('100%') } }

运行效果如图：

当点击Process–按钮：

代码结构与功能

1. 自定义修饰器类：MyProgressModifier

• 实现ContentModifier<ProgressConfiguration>接口
• 支持传入自定义颜色参数
• 通过applyContent()返回自定义 UI 构建器

2. 自定义内容构建器：myProgress

• 接收ProgressConfiguration进度配置
• 显示当前进度文本：config.value + '/' + config.total
• 绘制3 个星形 Path 图标，根据进度值动态变色
• 进度 ≥1 / ≥2 / ≥3 时分别点亮对应星星

3. 页面组件：Index

• 维护进度值currentValue（0~3）
• 创建修饰器实例并传入自定义颜色
• 环形进度条绑定contentModifier
• 提供 +/- 按钮控制进度

核心特性

1. 进度联动

通过config.value可直接获取当前进度，实现内容随进度自动更新。

2. 样式定制

可在修饰器中自定义：

• 文本、颜色、字体
• 图形、图标、路径
• 布局、间距、对齐

3. 状态感知

可通过config.enabled判断进度条是否可用，实现可用/不可用状态切换。

4. 完全替换原生内容

使用contentModifier后，原生百分比文本自动隐藏，完全展示自定义内容。

总结

1. 仅支持带内容区的进度条：主要为ProgressType.Ring（环形）
2. 必须实现接口：修饰器必须实现ContentModifier<ProgressConfiguration>
3. 构建器参数必传：@Builder必须接收ProgressConfiguration参数
4. 类型强转：使用修饰器自定义属性需as强转为自定义类
5. 自动刷新：进度值变化时，自定义内容会自动刷新

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力