uni-app 微信小程序上传需用 onUploadProgress 手动驱动 CSS 圆环进度条，通过 Math.min 限幅和 ≥2% 防抖避免跳变卡顿；注意左右半圆角度边界处理、transform-origin 及 overflow 隐藏；多端需降级适配，后台时进度停止，前端仅作体验示意。
uni-app 上传文件时怎么实时显示圆环进度条
想在微信小程序里实现上传进度条，你会发现事情没那么简单。官方的 progress 组件在这里帮不上忙——它只认下载或者内部加载，对 uni.uploadFile 的实时上传进度完全无感。所以，唯一的路径就是手动监听 onUploadProgress 回调，再用这个数据去驱动一个自定义的圆环动起来。
真正的难点，其实不在于画出那个圆环，而在于“如何让进度值从0平滑地走到100”。上传接口返回的是已上传字节和总字节数，但在早期阶段（特别是小文件），你可能会连续收到好几个0%的回调，或者进度突然从10%跳到80%。如果直接把这个值赋给UI，圆环就会出现卡顿甚至倒退的尴尬场面。
- 计算必须限幅：务必使用
Math.min(100, Math.round((loaded / total) * 100))来计算当前进度。这能有效规避浮点误差，并防止出现超过100%的数值。 - 更新需要防抖：加一层简单的逻辑：只在进度变化值 ≥ 2% 时才去更新页面的
data，否则就跳过这次渲染。这个技巧能大幅减少频繁setData带来的性能开销和卡顿。 - 选对渲染方案：圆环组件推荐使用纯CSS方案，而非Canvas。因为
uni.uploadFile的进度回调频率可能很高，在iOS小程序中，Canvas的频繁重绘容易导致掉帧。而CSS的旋转动画由渲染层优化，表现通常更稳定流畅。
为什么圆环进度条在真机上转半圈就停了
这几乎是每个开发者都会踩的坑，是左右半圆逻辑没有对齐的典型症状，尤其在49%跨越到51%这个临界点时最为明显。CSS圆环的本质，是两个半圆视图的叠加：左半圆负责0%到50%的部分，右半圆则接管50%到100%。如果角度计算没有做好边界处理，右半圆就会在进度达到50%的瞬间，从0°直接跳到180°，视觉上看起来就像“卡住”或者“回弹”了一下。
- 左半圆：旋转角度 =
progress （单位：deg）。 - 右半圆：旋转角度 =
progress > 50 ? (progress - 50) * 3.6 : 0。 - 定好旋转中心：务必给两个半圆的容器都加上
transform-origin: center样式，否则旋转中心一旦偏移，整个圆环就会错位。 - 检查溢出隐藏：如果在微信开发者工具里看着一切正常，到了真机上就出问题？大概率是因为
overflow: hidden没有写在最外层的容器上，导致旋转后的半圆溢出并被意外裁剪。
uni.uploadFile 的 onUploadProgress 在哪些平台不可用
需要明确的是，onUploadProgress 这个回调并非在所有平台都畅通无阻。它是 uni-app 2.7.14+ 版本才稳定支持的API。目前，在H5和微信小程序（要求基础库版本 ≥ 2.19.0）上可以正常使用。然而，在支付宝小程序、百度小程序、QQ小程序等平台上，该回调目前仍不被支持——这意味着在这些端上，你只能等待服务端返回“上传完成”的通知后才能更新UI，无法实现真正的实时进度反馈。
因此，如果你的项目需要发布到多个平台，就必须提前做好降级方案。核心思路是：检测当前平台是否支持 onUploadProgress，如果不支持，就改用“上传中…”文字提示配合骨架动画，而不是强行展示一个不会动的圆环进度条。
- 平台探测：可以使用
typeof uni.uploadFile === 'function' && 'onUploadProgress' in uni.uploadFile.toString()进行简单判断。 - 稳妥方案：更推荐的做法是在
manifest.json中利用条件编译，为不支持实时进度的平台单独提供静态的loading状态组件。 - 注意App端：iOS/Android的App端使用的是原生上传模块，
onUploadProgress行为与小程序基本一致。但部分旧版本的基座可能存在回调延迟的问题，建议将HBuilderX升级至4.20以上版本。
上传中用户切后台，进度条还能继续更新吗
答案是：不能。这是由平台机制决定的。微信小程序一旦被切到后台，Ja vaScript的执行就会被系统暂停，onUploadProgress 回调也会立即停止触发，UI自然就冻结在最后上报的那个进度值上了。等到用户再次切回前台时，上传任务可能已经完成，也可能已经失败，但中间那段“空白期”的进度是无法补全的。
这并非代码的bug，而是平台的运行策略。所以，这里有一个至关重要的原则：不要依赖前端进度条的数值来做任何关键的业务判断（例如“进度到90%就允许用户预览”）。所有最终的状态确认，都必须以服务端的回调为准。
- 状态持久化：可以在上传开始前，在本地存储一个标记，例如
uni.setStorageSync('uploading', true)。 - 恢复与提示：在页面onLoad时检查这个标记。如果标记存在，且没有收到明确的上传成功或失败回调，可以提示用户“检测到上次上传未完成，正在恢复…”。（注意，这里的“恢复”通常是重新发起上传请求）。
- 认清本质：真正的进度同步，需要依赖服务端通过WebSocket长连接或轮询来推动。前端的圆环，本质上只是用户体验层的“示意”，它并非可信的数据源。
说到底，画一个圆环并不难，难的是让它的转动节奏与真实的上传过程严丝合缝。很多人都会卡在这样一个阶段：进度条“看起来”在动，但动得并不“诚实”——要么跳跃式前进，要么中途卡死，要么一切到后台就失联。这些问题，其实都不是样式问题，而是认知问题：错把前端进度当成了一个确定性的信号。而实际上，它只是一个带有噪声的采样结果，需要经过平滑、限幅和降级处理，才能为用户提供既流畅又可靠的视觉反馈。
