企业官网建设流程全解析

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 不是 Android，RN 官方发布的 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 版本对应关系是最大的坑

我这次项目用的版本组合如下，可以作为参考基准：

版本对照是整个集成过程中最容易出问题的地方。@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 product=default

第一次编译会非常慢，因为要把 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 renderMode="SOFTWARE" 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 占位正常，但动画内容不出来，区域是黑底或者白底。

排查路径按顺序走：

1. 确认 JSON 文件有没有被正确加载。在 LottieView 的 onLoadStart 和 onLoad 回调里打印日志，看两个回调有没有触发。
2. 确认 JSON 格式合法。把 JSON 用 LottieFiles 网站或者本地播放器打开验证一遍。有些设计师从 AE 插件导出的 JSON 里可能带一些 OpenHarmony 解析器不支持的字段，导致解析到一半失败。
3. 检查动画的合成尺寸。如果 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 渲染器画到一个缓冲区，再被图形栈合成到界面上。当合成频率跟动画帧率不匹配时，旧帧没有被正确清除，看起来就是残影。解决方案是：

• 优先指定 renderMode="SOFTWARE"，减少 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 常见问题速查表

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 动画，我用的三件套是：

1. 在 LottieView 上挂 onAnimationStart、onAnimationEnd、onLoad、onError 回调，这些回调可以提供动画生命周期的关键信息。
2. 用 DevEco 的 Profiler 工具观察 CPU 和内存走势，判断动画帧率是否达标。
3. 使用 @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 目录是否存在、依赖声明是否完整、版本是否匹配，比编译报错后再来排查效率高一个量级。动画渲染这块，遇到画面异常优先怀疑合成链路，不要一上来就改业务逻辑。把这些基础工作做扎实，后面的坑会少很多。