rippleFields 不生效？一场存活两天的 API 版本错误归因翻案记（HarmonyOS）

现象： 波纹/速度场实验卡拖滑条，画面毫无反应——不报错、不崩溃、日志干净；旁边同组件的扰动场实验台活蹦乱跳。
原因： 不是 API 版本问题（设备实测 deviceInfo.sdkApiVersion = 26，测试版系统 7），而是三层设计缺陷叠加：粒子静止无 velocity / 场区域坐标硬编码越界 / 振幅上限 40 太小 + 穿场太快 + 衰减拖后腿；一个不公平的对照给出了错误的确定性。
解决： 粒子加 velocity 并降速增曝、场区 onAreaChange 绑实际尺寸、振幅上限放开到 300 默认 100、衰减归零——两场实测生效；归因类问题一律 deviceInfo.sdkApiVersion 实测说话。

一、误诊是怎么诞生的

particle.d.ts 里 rippleFields / velocityFields 标注 @since 22。波纹实验卡照 d.ts 写的，编译零警告，真机上滑条却纹丝不动。

我的推理链当时只有两步：从"没效果"一步跳到"版本不支持"，再用一个对照"印证"它——API 12 的扰动场拖动跟手，API 22 的波纹场没反应；同一个 app、同一套编译产物、同一台真机。看起来严丝合缝，我写下结论：“是设备系统版本的原因，不是代码问题”，把 rippleFields/velocityFields 搁置，决定以后相关测试一律跳过。

这个推理有一个致命缺口：我从未实测过设备的系统版本。“低于 API 22"是结论需要的假设，不是测出来的事实。而那个对照也不公平——扰动场是摸哪生效哪，场中心跟着手指走，永远在屏内、永远"生效”；波纹场固定挂在预览区里。拿一个"永远生效"的东西去反衬一个"没反应"的东西，对照本身就带着答案。

二、翻案触发器：降级 UI 没有出现

两天后，我给波纹卡加了 apiAtLeast(22) 运行时门槛：设备真低于 API 22 就显示降级 UI。

结果降级 UI 没有出现。 设备 API ≥ 22，与原归因直接矛盾。一行 deviceInfo.sdkApiVersion 日志坐实：测试机是测试版系统 7，API 26——高于 API 22。

两个场从来都生效，隔开它们的不是系统版本，是我自己代码里的三层缺陷。

三、真因：三层设计缺陷

层	缺陷	后果
粒子层	粒子静止无 velocity	场对没有速度的粒子无能为力
场区层	场区域坐标硬编码越界（速度场 y460+ 整个在预览区外）	场在屏外空转
力度层	振幅上限 40 太小 + 粒子 40-90 vp/s 穿场太快 + 衰减 20% 削弱	即便生效也被快速穿场稀释

四、三轮修复与验证

1. 粒子层：加 velocity 并降速增曝——speed [10,25]，穿场 8-20 秒 → velocityFields 底部 30% 加速/托举对照明显
2. 场区层：onAreaChange 绑定实际预览尺寸（波纹全屏、速度场底部 30%）→ 场区回到屏内
3. 力度层：振幅上限 40→300 默认 100，衰减归零 → rippleFields 振幅 100+ 肉眼可见；调到 300 时粒子被周期性横推扩散

五、方法论沉淀

• 归因必须实测：一行 deviceInfo.sdkApiVersion 日志胜过两天猜测；禁止从"没效果"反推"版本不支持"
• 公平对照原则：对照双方必须受同等约束——不公平对照比不对照更危险，它给出错误的确定性
• 自洽 ≠ 正确：错误归因与所有观察自洽，只与新证据矛盾。翻案触发器出现时立即复查归因链，别给旧结论打补丁

翻案后沉淀的可复用诊断工具链四件套：apiAtLeast() 运行时门槛（带降级 UI）+ API 徽章常显 + 「区域」可视化开关 + 参数压力测试。

相关阅读

• 上一篇：《HarmonyOS 粒子特效实战总纲：PhotoMotion 立项全景与 15 坑分布图》
• 下一篇：《hvigor 多模块三坑：HAR module.json5 / --modules / oh_modules（HarmonyOS）》

标签

#HarmonyOS #ArkUI #粒子特效 #rippleFields #velocityFields #错误归因 #问题排查 #apiAtLeast

📹 效果演示：本文的「波纹场/速度场翻案对照」动态效果实录会发在抖音——号 581821159（天行健之初九）