鸿蒙ASCF组件实战：icon与progress用法和坑点

鸿蒙专家

表单页的校验状态、文件上传的进度条、下载任务的百分比……这一类“状态加进度”的展示需求，在 HarmonyOS 应用里用 icon 和 progress 两个基础组件就能快速搞定，不需要额外引图片，也不用自己拿 view 画矩形。这两个组件单独看都不复杂，但实际用起来各有几个细节值得注意，我把开发中的用法和踩过的坑一起整理出来。

icon：内置 14 种图标，开箱即用

icon 组件不需要引入图片资源，直接通过 type 属性指定内置图标，一共支持 14 种。登录成功、加载等待、警告提示这些常见状态都有对应的类型：

2. <icon type="success" size="80" color="#10b981"></icon>
3. <icon type="waiting_circle" size="40" color="#0A59F7"></icon>
4. <icon type="warn" size="24" color="#ff9500"></icon>

复制代码

size 的默认值是 23px，也可以传入 rpx 单位做屏幕适配；color 使用 CSS 色值就行。刚开始用的时候可能会觉得 14 种 type 偏少，但实际开发中高频使用的也就是 success、warn、info、search、clear 这几个，覆盖常见状态场景已经够用了。

icon 有两点约束要知道。第一，icon 本质上是图片，不能响应点击事件。要做可点击的图标，就在外面包一层 view，配合 hover-class 做按压反馈：

2. <view hover-class="icon-btn-hover" bindtap="onIconTap">
3.   <icon type="search" size="20" color="#666"></icon>
4. </view>

复制代码

第二，icon 不支持修改内部路径，也不能替换成自己设计的图标。要用自定义图标，还是得走 image 组件或 iconfont 方案。

progress：原生进度条，动画和圆角都省心

progress 是系统原生绘制的进度条，比用 view 自己拼矩形省事很多，同时支持动画过渡和圆角样式。最简单的文件上传进度展示：

2. <progress percent="{{uploadPercent}}" show-info="{{true}}"
3.   stroke-width="6" border-radius="3"
4.   activeColor="#0A59F7" backgroundColor="#e5e5e5">
5. </progress>

复制代码

percent 绑定进度百分比数据，show-info 设为 true 会在进度条尾部显示百分比文本。

动画：backwards 和 forwards 两种模式

active 属性置为 true 后，percent 变化时进度条会平滑过渡，而不是瞬间跳变。active-mode 控制动画的起始位置：

backwards（默认）：每次 percent 变化都从 0 开始播放动画；
forwards：从上一次结束的位置接续动画。

2. <progress percent="{{percent}}" active="{{true}}" active-mode="forwards"></progress>

复制代码

duration 控制动画速度，默认值 30，表示每增加 1% 进度耗时 30ms，从 0 到 100 就是 3 秒。按产品需求调整数值即可：

2. <progress percent="{{percent}}" active="{{true}}" duration="10"></progress>
3. <progress percent="{{percent}}" active="{{true}}" duration="50"></progress>

复制代码

模拟一个实时文件上传进度，每次随机增加 5 到 20，500ms 更新一次：

2. let progress = 0;
3. const timer = setInterval(() => {
4.   progress += Math.floor(Math.random() * 15) + 5; // 每次 +5~20
5.   if (progress > 100) progress = 100;
6.   this.setData({ percent: progress });
7.   if (progress >= 100) clearInterval(timer);
8. }, 500);

复制代码

样式定制：不带百分比的简洁模式

不设 show-info 时，进度条只显示条本身，适合不需要数值文本的场景。想在左侧加一些描述文字，自己拼一下布局：

2. <view class="progress-row">
3.   <text class="progress-label">{{fileName}}</text>
4.   <progress percent="{{percent}}" stroke-width="6"
5.     border-radius="3" activeColor="#0A59F7">
6.   </progress>
7. </view>

复制代码

组合场景：状态展示与下载管理

详情页里的多条状态，用 icon 加 text 组合展示：

2. <view class="status-row">
3.   <icon type="success_circle" size="20" color="#10b981"></icon>
4.   <text class="status-text">认证通过</text>
5. </view>
6. <view class="status-row">
7.   <icon type="warn" size="20" color="#ff9500"></icon>
8.   <text class="status-text">材料待完善</text>
9. </view>
10. <view class="status-row">
11.   <icon type="cancel" size="20" color="#ff3b30"></icon>
12.   <text class="status-text">审核未通过</text>
13. </view>

复制代码

下载管理列表里，icon 标识文件类型，progress 展示实时进度，右侧单独放百分比文本：

2. <view class="download-item">
3.   <view class="download-top">
4.     <icon type="download" size="18" color="#0A59F7"></icon>
5.     <text class="download-name">更新包 v2.3.0</text>
6.     <text class="download-pct">{{percent}}%</text>
7.   </view>
8.   <progress percent="{{percent}}" show-info="{{false}}"
9.     stroke-width="4" border-radius="2"
10.     active="{{true}}" duration="15"
11.     activeColor="#0A59F7" backgroundColor="#e5e5e5">
12.   </progress>
13. </view>

复制代码

踩坑记录：六个实际开发中遇到的问题

icon 的 size 默认单位是 px，不是 rpx。文档说支持传入单位，但默认按 px 解析。写 size="100" 在不同屏幕密度下显示大小不一致，需要精确适配的页面里，我一般显式写成 size="{{48rpx}}"。

icon 不传 color 时，不同 type 的默认颜色不一样。有的 type 用黑色，有的用灰色。要保持视觉统一，就全部显式传 color。

progress 的 border-radius 设了没生效。圆角要配合 stroke-width 看效果。线宽 8px 时，border-radius 设 10px 因为超过线宽看不出变化。圆角最大值建议等于 stroke-width / 2。

activeColor 和 color 冲突。文档里说两者作用一样，但两个都设时以 activeColor 为准。之前两个设了不同值，排查半天才发现是优先级问题。新代码直接用 activeColor，别混用。

duration 的动画时间不精确。duration 设为 30 表示每 1% 花 30ms，但 JS 执行和渲染队列的延迟会让整体时长比理论值偏长。高精度计时场景不能依赖 duration 做时间计算。

bindactiveend 触发时机有限制。只有 percent 到达 100% 且动画播放完毕后才会触发。如果进度最终停在 80%，不会触发这个事件。想监听每次进度变化，用 setData 的 callback 或者观察者模式。

小结

icon 和 progress 都是拿来就能用的基础组件，不需要额外引资源。icon 胜在简单，14 种内置图标覆盖大部分常见状态展示；progress 在需要展示进度的上传、下载场景里，比自己用 view 画矩形省事得多。如果你的场景需要自定义图标，或者要动态切换多个图标，那就用 image 组件或 iconfont 方案替代。

热心网友4

楼主整理得很实用，尤其是 icon 不能点击和 progress 动画模式这两个点，实际项目里确实容易踩。我补充一个自己遇到的小坑：progress 的 show-info 显示百分比文本时，如果进度条宽度比较窄，文字会和条挤在一起，后来我给外层加了个 padding 才舒服些。另外 active-mode 的 backwards 和 forwards 区别，之前一直没搞明白，看了你这解释总算清晰了，感谢！

热心网友4

感谢楼主分享，正好最近在搞鸿蒙表单和上传这块，icon和progress这两个组件确实够用。icon不能点这点太真实了，只能包一层view做点击，刚开始容易踩。progress的backwards和forwards动画模式我之前没太注意，默认从0开始播，有时候进度回跳看着怪，换成forwards就顺了。另外那个duration默认30的换算也挺实用，调进度动画速度心里有数了。

热心网友4

感谢楼主整理，实战经验很实用。icon不能点这个坑我也踩过，确实得包一层view才能做交互，不过这样反而更好控制点击区域和反馈效果。progress的forwards模式我之前没注意到，默认backwards每次从头动画确实会有点突兀，下载续传这种场景用forwards更自然。 另外补充一个小点：progress如果percent设了小数，显示的时候可能带一堆尾巴，记得先取整或者保留一位小数，不然界面会有点凌乱。还有activeColor和backgroundColor最好显式设置，不然不同设备默认值不一样，容易跟页面风格不搭。