1. 为什么要在 OpenHarmony 上折腾 RN 和 lottie先说结论在 ReactNative 项目的 OpenHarmony 适配过程中lottie-react-native 这类三方库往往是比业务代码本身更让人头疼的部分。业务代码是自家写的逻辑不对可以改三方库是别人封装的底层依赖一堆出问题你连从哪下手都不知道。我这次做的就是把这套流程完整走一遍记录怎么把 lottie-react-native 集成到 OpenHarmony 的 RN 工程里包含从环境准备、依赖安装到渲染调优的全部细节。在讲集成之前先理清楚一个核心问题为什么动画方案里我选 lottie而不是逐帧序列图或者 CSS/JS 动画。逐帧序列图的缺点是明显的一张 1080p 的 PNG 动辄几百 KB一套 30 帧动画放进去包体积直接爆炸。CSS 动画和 JS 动画在跨端一致性上又太差同一套动画在 Android 和 iOS 上能差出半秒更别说换到 OpenHarmony 上。而 lottie 是用 JSON 描述矢量动画体积小、缩放不失真、渲染效果在同一套 Lottie 实现下能做到高度一致这正是多端业务最需要的。但这里有一个很关键的现实问题OpenHarmony 不是 AndroidRN 官方发布的 lottie-react-native 并没有为 OpenHarmony 做原生适配。它底层依赖 Android 的 LottieAnimationView 和 iOS 的 Lottie 框架在 OpenHarmony 上直接跑是跑不起来的。所以我们要用的实际是社区适配版本也就是 OpenHarmony 生态里针对 RN 的 lottie 移植实现这跟你平时在普通 RN 项目里直接 npm install lottie-react-native 是完全两条路。另外要提前说清楚这套方案适合谁如果你的 RN 工程已经能跑在 OpenHarmony 设备上也就是说 RN 的 OpenHarmony 运行时已经通了你只是想加动画那这篇文章是给你看的。如果你的 RN 工程连 OpenHarmony 设备都还没跑起来那第一步不是集成动画库而是先把 RN 的 OpenHarmony 基础链路打通那属于另一个话题。2. 集成前必须确认的环境与版本匹配2.1 OpenHarmony 适配版 lottie-react-native 的来源在 OpenHarmony 生态里RN 三方库的适配通常走的是 react-native-oh-tpl 前缀这是 OpenHarmony 的 RN 适配社区维护的一套模板库命名规范。lottie-react-native 对应的适配包是 react-native-oh-tpl/lottie-react-native它的 API 设计和原版基本保持一致但底层渲染改成了 OpenHarmony 自绘引擎的实现。这里要提醒一句安装时看清楚包名别装成原版 lottie-react-native。我见过有人直接 npm install lottie-react-native然后发现 OpenHarmony 设备上一编译就报错 LottieAnimationView not found。原版是给 Android/iOS 用的它的原生代码目录里根本没有 OpenHarmony 的 harmony 实现。2.2 版本对应关系是最大的坑我这次项目用的版本组合如下可以作为参考基准组件版本OpenHarmony SDK5.0.0 Release 及以上DevEco Studio5.0.0 及以上React Native0.72.xreact-native-oh-tpl/lottie-react-native5.1.6-0.2.0 这个系列react-native-harmony配套 0.72.x 的适配版版本对照是整个集成过程中最容易出问题的地方。react-native-oh-tpl/lottie-react-native 对 RN 的版本是强依赖的因为 RN 的原生桥接接口在不同版本之间可能有变化适配库如果没跟上编译期就会在原生代码里报一些找不到符号之类的错误。我的建议是先确定你的 RN 版本再到 OpenHarmony 的 RN 三方库索引页去搜 lottie找到对应你 RN 版本的适配版本号。不要贸然用最新版最新版不一定适配你的 RN 版本这在三方库集成里是普适规律。2.3 确认你的 RN 工程已经具备 OpenHarmony 构建能力只有当你打开工程目录能看到 harmony 文件夹且里面已经有了 entry/src/main/ets 这类 OpenHarmony 工程结构时才适合继续往下走。如果没有你需要先通过 react-native-oh-tpl/react-native-harmony 完成 RN 工程的 OpenHarmony 化改造一般是用社区提供的命令行工具自动生成 harmony 目录然后再回来集成 lottie。另外本机要安装好 DevEco Studio 命令行工具 hvigor因为 OpenHarmony 侧的依赖编译和打包是通过 hvigor 来执行的不是 npm。后面集成过程中npm 管 JS 依赖ohpm 管 OpenHarmony 原生依赖hvigor 管构建三个工具各管一段别搞混。3. 核心实操从依赖安装到跑通第一个动画3.1 安装依赖的正确顺序在 RN 工程根目录执行npm install react-native-oh-tpl/lottie-react-native --save装完以后你会发现 node_modules 里多了一个 lottie-react-native 目录注意npm 包名带前缀但 node_modules 里的目录名是 lottie-react-native。先进这个目录看一眼确认里面有 harmony 子目录这是 OpenHarmony 原生实现存在的标志。如果没有 harmony 目录那你装的一定是原版赶紧卸了重装。原生侧还需要确认 lottie 的 OHOS 实现依赖是否被正确拉取这一步通常在项目构建自动完成但如果你用了 monorepo 或者 yarn workspace可能要手动在 harmony/oh-package.json5 里添加依赖声明。手动添加的格式大概是dependencies: { ohos/lottie: ^2.0.0 }ohos/lottie 是 OpenHarmony 官方的 Lottie 渲染库react-native-oh-tpl/lottie-react-native 在原生侧就是对它的进一步封装。如果你发现 node_modules 里的适配包没把依赖声明清楚就需要在 harmony/oh-package.json5 里手动补上然后用 ohpm install 拉取。3.2 业务侧代码的最小示例依赖装好后JS 侧的使用方式跟原版非常接近import LottieView from lottie-react-native; function AnimationDemo() { return ( LottieView source{require(./assets/animations/loading.json)} autoPlay loop style{{ width: 200, height: 200 }} / ); }这段代码如果在普通 RN 工程里已经可以跑了。但在 OpenHarmony 工程里你还需要重点检查一个东西动画 JSON 文件到底放到了哪里以及运行时能不能被正确加载。这往往是初次集成时最容易出现黑屏或白屏的根源后面专题讲。3.3 编译与同步的完整流程真正的 OpenHarmony 侧编译入口在 harmony 目录下用 DevEco Studio 打开 harmony 目录或者直接用命令行cd harmony hvigorw assembleHap --mode module -p productdefault第一次编译会非常慢因为要把 RN 的 OpenHarmony 原生代码和 lottie 的 OHOS 实现一起编进去建议耐心等。如果你是在 DevEco Studio 里开发需要在 File Sync and Sync Project 触发一次原生依赖同步否则刚装好的三方库不会进入构建。我还遇到过一个情况JS 侧 bundle 已经更新了但设备上动画还是旧的。这是因为 OpenHarmony 的 RN 应用默认把 bundle 打包进了 HAP需要重新构建 HAP 才会更新静态资源。调试阶段可以用 RN 的 Metro 服务加载远程 bundle让动画 JSON 从 Metro 的 require 系统走这样才能热更新调试。具体做法是在工程的 MainActivity 配置里把 bundle 加载地址指向 Metro 服务这在 RN 的 OpenHarmony 适配文档里有标准配置照着填 IP 和端口就行。3.4 source 参数里的两种传法要分清lottie-react-native 的 source 有两种传法一种是 require 本地 JSON一种是传 uri 远程地址或纯对象。在 OpenHarmony 上这两种传法的内部实现路径完全不同。require 本地 JSON 的方式打包时 JSON 会被交给 Metro 处理转成一个包含 id 的资源对象运行时由原生侧根据 id 去解析。这种方式在 OpenHarmony 上相对稳定但前提是 Metro 的 asset 注册表能正常工作。远程 uri 的方式原生侧直接请求网络或本地文件路径然后交给 lottie 渲染器解析。调试初期建议先用 require 模式把动画跑起来再去测远程模式减少变量。这里有一个隐藏很深的兼容问题某些版本的适配库里source 传 require 的 json 对象时动画的 JSON 字段解析依赖原生侧的 JSONObject 实现如果你的动画 JSON 里包含超大数字或者特殊 Unicode 字符解析可能直接失败。遇到这种情况能改动画文件就改文件不能改就换一种传法两种都试试。4. 动画资源与渲染细节深度解析4.1 JSON 资源到底该放哪这是很多新手第一次集成时踩的第一个坑。在普通 RN 工程里require 一个 JSON 文件Metro 会把它当成 JS 模块的一部分打包进去。但在 OpenHarmony 的适配工程里Metro 的打包结果最终要经过一次转换才能进 HAP这个转换链路对 JSON 静态资源的处理不如 JS bundle 那么成熟。实操中我最终采用的方案是把动画 JSON 文件同时复制一份到 harmony/entry/src/main/resources/rawfile/ 目录下然后用相对路径去加载。也就是LottieView source{{ uri: rawfile:///loading.json }} autoPlay loop style{{ width: 200, height: 200 }} /rawfile 是 OpenHarmony 应用资源的标准目录应用安装后会被打进 HAP 的 resources 目录运行时可以通过 rawfile:// 协议读取。这个方案不依赖 Metro 的 asset 打包链路是最稳的。缺点是资源文件需要双份维护但动画文件一般不会频繁改动复制一下的成本可以接受。如果你不想用双份维护也可以自定义一个加载函数从应用沙箱或者网络下载目录读取 JSON 字符串然后直接解析成对象传给 source。这种灵活性更高但要自己负责资源生命周期我没采用因为业务复杂度不够没必要。4.2 动画中引用的图片和字体资源lottie 动画不是只能画矢量图形很多设计师会在 After Effects 里把位图素材和字体文本放进动画。导出 JSON 时位图素材会被编码成 base64 字符串内嵌到 JSON 里或者作为外部图片资源引用字体则是通过 JSON 里的 fonts 字段声明。问题出在这里OpenHarmony 的 lottie 渲染器对字体资源的支持不如 Android 完整。如果你的动画里有文字渲染时可能会发现文字全部变成了方块或者直接缺失。我在一次加载引导页动画时就遇到这个情况动画里的几个中文字完全不显示。排查思路是这样的先用文本编辑器打开 JSON搜索 fonts 和 assets。如果 fonts 里声明的字体名称在 OpenHarmony 系统里不存在就把字体文件放到 rawfile 目录然后在 lottie 初始化时注册字体映射。具体接口在 ohos/lottie 的文档里有实际使用需要调用 Lottie 的 setFontMap 之类的方法。如果你用的适配包没暴露这个能力那更稳妥的办法是请设计师把文字转成形状图层再导出一次避开字体渲染的不确定性。位图资源同理如果 JSON 里的 assets 是外部引用也要确保图片能被 lottie 渲染器正确找到。最简单的验证方式是检查 JSON 的 assets 里是否有 u 字段也就是图片的 URI 或 base64 位置。内嵌 base64 的在 OpenHarmony 上通常没问题外部引用的必须确保路径可访问。4.3 renderMode 的选择与适配LottieView 有一个 renderMode 属性可选值是 AUTOMATIC、HARDWARE、SOFTWARE。在 Android 上HARDWARE 模式用硬件加速渲染可以提高性能但可能引入一些渲染边界问题SOFTWARE 模式是纯 CPU 绘制渲染稳定但性能上限低。在 OpenHarmony 上我实际测试下来AUTOMATIC 模式在部分设备上会把动画渲染到一个离屏缓冲再合入页面这一步偶尔会导致画面渲染异常具体表现是动画区域出现黑块或者残影。这个现象在低端设备上更明显。所以我的建议是OpenHarmony 环境下优先指定 SOFTWARE 模式保证渲染稳定性。如果你的动画确实复杂、而且设备性能足够再尝试 HARDWARE但要充分测试不同机型。LottieView source{{ uri: rawfile:///loading.json }} autoPlay loop renderModeSOFTWARE style{{ width: 200, height: 200 }} /4.4 resizeMode 也对渲染结果有影响lottie-react-native 还提供了 resizeMode 属性它控制动画内容在容器内的缩放对齐方式。常见值有 cover、contain、center 等。在 OpenHarmony 上某些版本对 resizeMode 的部分取值支持不好比如 center 可能出现动画被裁切一半的问题。我这边测下来比较安全的是 contain也就是保持宽高比完整显示整个动画。cover 在目标容器跟动画原始宽高比接近时也能用但如果差距大动画边缘会被裁掉。如果你发现动画内容显示不全优先查 resizeMode 而不是动画文件本身这个方向排查会更快。5. 常见问题与排查技巧实录5.1 动画区域黑屏/白屏这是集成后最常见的问题优先级排第一。现象是 LottieView 占位正常但动画内容不出来区域是黑底或者白底。排查路径按顺序走确认 JSON 文件有没有被正确加载。在 LottieView 的 onLoadStart 和 onLoad 回调里打印日志看两个回调有没有触发。确认 JSON 格式合法。把 JSON 用 LottieFiles 网站或者本地播放器打开验证一遍。有些设计师从 AE 插件导出的 JSON 里可能带一些 OpenHarmony 解析器不支持的字段导致解析到一半失败。检查动画的合成尺寸。如果 JSON 里宽高是 0 或者特别大渲染器可能直接放弃绘制这也表现为白屏。手动给 LottieView 设置明确的 width 和 height 可以绕过这个问题。我还遇到过一种特殊情况动画本身没问题但页面所在容器用了 overflow: hidden而动画在初始化时会提前渲染一帧超出容器范围的画面导致该区域被裁剪后看起来像没渲染。去掉 overflow 或者改用 margin 控制布局能解决。5.2 只播放第一帧或者动画卡在中间这个现象通常是 resizeMode 或 renderMode 和动画实际尺寸不匹配造成的。卡在中间帧的多半是动画被放在了一个不断触发布局更新的容器里比如 ScrollView 里布局抖动导致渲染中断。OpenHarmony 上布局抖动的影响比 Android 更明显。因为 OpenHarmony 的自绘渲染引擎在合成动画时需要重新走一遍图形绘制管线只要容器尺寸变一次动画就重新初始化一次。解决办法是把 LottieView 的尺寸固定下来不要用 flex: 1 或者百分比宽度。5.3 动画闪烁、残影、画面渲染异常搜索热词里有openharmony画面渲染异常指向的就是这类问题。在 OpenHarmony 设备上跑 lottie 动画时动画区域偶尔会出现闪烁或者残影尤其在页面滑动过程中格外明显。我的判断是这跟 OpenHarmony 图形栈的合成策略有关。动画帧是由 lottie 渲染器画到一个缓冲区再被图形栈合成到界面上。当合成频率跟动画帧率不匹配时旧帧没有被正确清除看起来就是残影。解决方案是优先指定 renderModeSOFTWARE减少 GPU 合成链路的参与度。动画所在页面避免使用透明度动画同时叠在 LottieView 上层。尝试给 LottieView 增加一个稳定背景色消除透明区域的合成不确定性。经过我的实测SOFTWARE 模式能解决大部分闪烁问题但代价是 CPU 占用升高。如果你的动画比较长而且设备性能弱CPU 占用会导致整体卡顿这时候就要权衡了。我的方案是短动画用 SOFTWARE长动画在高端设备上保留 AUTOMATIC但通过真机多轮验证。5.4 动画控制方法完全失效比如调用 play()、pause()、reset() 无效。这个问题的根源通常是 LottieView 的原生实例还没有创建完成JS 侧就调用了方法。原版库在 Android/iOS 上对这种情况做了容错但 OpenHarmony 的适配版容错可能没那么完善。解决方案是在动画加载完成的回调里再执行控制操作const ref useRef(null); LottieView ref{ref} source{...} onLoad{() { ref.current?.play(); }} /另外一个常见控制失效场景设置了 loop 属性后动画播完还是不循环。这通常是动画 JSON 本身没有循环标记LottieView 的 loop 属性对这种 JSON 的覆盖能力在不同平台上有差异。可以在动画 JSON 里找到 markers 段或者直接在 LottieView 上设置 speed 和 loop 组合来强制控制。5.5 常见问题速查表现象可能原因排查/解决方案代码一编译就报找不到原生模块装成了原版 lottie-react-native卸载改装 react-native-oh-tpl/lottie-react-native动画区域黑屏/白屏JSON 资源未正确加载改用 rawfile:// 方式加载资源打印 onLoad 回调日志动画只渲染第一帧容器尺寸变化触发重新初始化固定 LottieView 宽高画面闪烁/残影图形栈合成策略问题指定 renderModeSOFTWARE页面避免叠加复杂透明动画动画里有文字不显示字体资源缺失或解析器不支持请设计师把文字转形状图层或手动注册字体映射控制方法无响应原生实例未就绪在 onLoad 回调后再调用控制方法多动画页面内存暴涨每帧位图缓存未释放复用一个 LottieView 实例切换时复用减少实例创建远程 JSON 加载超时网络库兼容性问题先把 JSON 下载到沙箱再加载绕开网络链路6. 性能优化与实战心得体会6.1 大 JSON 动画的加载优化lottie 动画的 JSON 越大渲染器解析耗时越长。在 OpenHarmony 的底层实现里JSON 解析是同步的也就是说解析过程中 JS 线程会被阻塞一个 2MB 的动画能让你看到明显卡顿。我这里有一个经验值单动画 JSON 最好控制在 500KB 以内。如果超过了先让设计师减少图层数量或路径顶点数不要轻易相信设计师说这个动画导出就这么大的说法。AE 里一个多余的形状图层、一个多余的关键帧都会直接体现在 JSON 体积上。压缩掉不必要的图层后体积能显著下降。另外lottie 动画里最影响渲染性能的往往是带渐变、阴影、模糊这类效果的图层。在移动端上这些效果的渲染开销非常大OpenHarmony 的图形栈对这些效果的支持也不完善能去掉尽量去掉。6.2 多个动画共存的实践经验如果你一个页面里要同时出现多个 LottieView性能压力会成倍增加。我的做法是能合并成一个动画就合并比如多个图标同时出现可以合成一个动画减少渲染器实例。如果确实要多个复用一个实例然后动态切换 source比创建多个实例靠谱。不过切换 source 也要注意频繁切换会触发资源的重复加载可以先把 JSON 缓存到一个全局变量切换时直接传对象。在架构上建议把 LottieView 的创建和销毁放到一个统一的组件管理器里避免业务代码里到处散落动画组件。这样一旦 OpenHarmony 上出现渲染问题你有唯一的排查入口而不是一个个业务页面去翻。6.3 用缓存策略降低内存占用lottie 动画在渲染过程中会把每一帧的图形计算结果缓存下来如果你的动画很长而且不循环缓存会一直增长。OpenHarmony 对内存的管理比 Android 更严格一旦内存警报应用可能直接被杀掉。建议给动画设置合理的 speed比如 1.5 倍速减少总帧数。不需要循环的动画播完就清掉引用不要保留在状态里。在页面不可见时主动暂停动画比如配合 AppState 监听前后台切换。6.4 排查工具与调试技巧调试 lottie 动画我用的三件套是在 LottieView 上挂 onAnimationStart、onAnimationEnd、onLoad、onError 回调这些回调可以提供动画生命周期的关键信息。用 DevEco 的 Profiler 工具观察 CPU 和内存走势判断动画帧率是否达标。使用 ohos/lottie 的日志输出能力把 lottie 内部的绘制日志打开定位是渲染阶段出错还是合成阶段出错。这里有个小技巧在调试模式下把动画的 source 换成一份非常简单的测试 JSON一个圆形从 A 点移动到 B 点如果测试 JSON 能正常播放那问题大概率出在原动画内容本身而不是集成链路。这种二分排查法能帮你快速缩小问题范围。6.5 后续扩展方向lottie-react-native 跑通后依赖同一套原生桥接思路还可以继续集成其他常用 RN 动画相关的三方库比如 react-native-reanimated 的 OpenHarmony 适配或者 react-native-svg 的适配版本。它们跟 lottie-react-native 的适配套路高度相似找 react-native-oh-tpl 前缀的库确认 RN 版本对应关系检查 harmony 原生目录然后编译调试。有了 lottie 的经验你会觉得 OpenHarmony 上集成任何 RN 三方库都不再可怕。个人实际操作下来的体会是OpenHarmony 的三方库适配质量参差不齐不要只盯着 API 表面去写业务代码。安装前多花十分钟检查 harmony 目录是否存在、依赖声明是否完整、版本是否匹配比编译报错后再来排查效率高一个量级。动画渲染这块遇到画面异常优先怀疑合成链路不要一上来就改业务逻辑。把这些基础工作做扎实后面的坑会少很多。