HarmonyOS 粒子特效实战总纲：PhotoMotion 立项全景与 15 坑分布图

现象： 想做"照片 + 华为系统特效 → 动态画面预览"的创作工具，从零起步直面粒子系统的复杂：一路 15 坑，最扎眼的一幕是"代码照着 d.ts 写、编译零警告，真机上却毫无反应"。
原因： ArkUI 粒子组件（Particle）签名复杂（particle.d.ts 2276 行），行为与直觉差异大——时序（emitRate）、定位（emitter.size）、状态（@Local）处处有坑，且效果不显示时极易错误归因。
解决： 双轮驱动蓝图 + d.ts 权威清单 + 真机实验台三件套；15 坑全部记录在案、每坑有因有解，本合集逐篇拆解。

一、项目缘起：PhotoMotion

照片躺在相册里是静态的，配上雪花的飘落、星光的闪烁、Ken Burns 式的缓慢推拉，它就"活"了。PhotoMotion 就是干这个：照片 + HarmonyOS 系统特效 → 动态画面预览，未来生成视频。

蓝图收敛成"双轮驱动"：

• 特效实验室（学习侧）：粒子/转场/滤镜/Ken Burns 实验台，滑条调参实时预览，玩明白的参数存为预设
• 创作编辑器（产品侧）：PhotoViewPicker 选照片（免权限）→ 照片轨道 → 叠加特效 → 全屏动态预览

两轮之间靠 EffectDescriptor 数据模型打通，架构三模块：

entry（产品壳） → common（共享模型 + 渲染组件 HAR） ← lab（特效实验室 HAR）

实验代码与产品代码编译期隔离，lab 里怎么折腾都不污染主干。

二、知识地基：55 项特效全量清单

动手写代码前，先把本地 SDK 的 d.ts 声明文件翻了个底朝天，整理出《华为特效全量清单》——11 大类 55 项，每项三段式（长什么样 / 能做成什么 / 怎么用），每个签名逐一对照 d.ts 核实。14 处抽查修正了 2 处凭印象写错的签名，还确认了一批"文档里传说中的 API"SDK 里根本不存在（ambientLight、morphTransition 等）。

d.ts 是最终权威——这条纪律在后来的头号坑里救了命（见 01）。

三、实验台：6 卡 → 22 卡

首批 6 个粒子实验台上真机（发射器/属性动画/图片粒子/扰动场/波纹速度场/配方合集），后扩展为 22 卡实验台 + 自由创作台：一属性一卡（发射器 6 / 粒子 3 / 属性 9 / 场系统 4 + 配方页），分屏对照 + 顶部文档条；多层粒子配方用 22 参数 CSV 持久化。

四、15 坑分布图

类型	坑	详见
构建	坑1 HAR 缺 module.json5 / 坑2 oh_modules 进 git / 坑3 Multiple entry modules	02 篇
头号翻案	坑7 "API 22 静默无效"是误诊——设备实测 API 26，真因三层设计缺陷	01 篇
时序	坑11 emitRate 出生延迟 / 坑12 同帧交接黑缝	03 篇
定位	坑10 emitter.size 随机出生区	04 篇
性能	坑9 desiredRegion 重复读盘 / 坑8 一发射器一图	05 篇
状态	坑13 Stack 默认居中 + ProgressMask 失效 / 坑14 plain private 不重求值	06 篇
编译级小坑	坑5 SliderChangeMode / 坑6 router 已废弃 / 坑15 Image 位置参数	02 篇附录
已销案	坑4 横向滚动"反向"——滚动条滑块正常视觉，横向条统一 scrollBar(BarState.Off) 即了结	本篇销案

五、三大教训

1. 归因必须实测："静默无效"的结论自洽地活了两天，最终被一行 deviceInfo.sdkApiVersion 日志推翻（01）
2. 性能先采基线：马赛克切块提速 17.6×~38×，突破口来自"每块成本不随块尺寸缩小而下降"这个判别信号（05）
3. 时序有语义：挂载 ≠ 显示，emitRate 默认 5 意味着首颗粒子可能晚生 1 秒（03）

相关阅读

• 合集入口：本篇（总纲）
• 下一篇：《rippleFields 不生效？一场存活两天的 API 版本错误归因翻案记（HarmonyOS）》

标签

#HarmonyOS #ArkUI #粒子特效 #Particle #PhotoMotion #hvigor #ArkTS

📹 效果演示：本合集的粒子消散、马赛克飞散、波纹场等动态效果实录会发在抖音——号 581821159（天行健之初九），截图看不出的粒子细节，视频一眼就懂。