最近在做一个 OpenHarmony 平台的应用适配遇到一个很有代表性的需求产品要求复用现有 React Native 技术栈在 OpenHarmony 设备上实现一套 Video 播放列表功能。说它典型是因为这个需求既包含了“RN 能不能跑在 OpenHarmony 上”的疑问又要解决“播放列表”这种完整业务场景下的状态管理、生命周期、资源释放等一系列问题。网上关于 RN 适配 OpenHarmony 的资料还没到烂大街的程度视频播放列表这种完整闭环的案例更少基本是边踩坑边摸索。我把自己这套方案的落地方案、代码骨架和排查记录整理出来给做 RN OpenHarmony 的团队一个参考。先把结论放在前面OpenHarmony 上跑 React Native 是可行的而且视频播放这种能力用 RN 业务层 原生播放器桥接的方式做代码复用率很理想。播放列表的核心难点不在“播放”而在“状态”。一旦把播放器的生命周期、列表索引、播放模式和 UI 状态理顺了整个功能就算立住了一半。剩下一半是平台适配层也就是让 RN 侧拿到 OpenHarmony 原生播放器的能力。下面按我的实现顺序展开来说。1. 为什么选 React Native 做 OpenHarmony 的视频应用1.1 跨端方案的选择逻辑先说项目背景。团队原来的移动端是 React Native 技术栈iOS 和 Android 两端的业务层代码已经稳定跑了两年多。现在要切入 OpenHarmony 生态最理想的情况自然是业务代码尽量少改只替换平台能力层。OpenHarmony 本身提供了 ArkUI 声明式开发框架但把现有 RN 业务完全用 ArkUI 重写一遍成本和时间都不可控。相比之下RN 适配 OpenHarmony 的方案能把 JS 层的基础组件和业务逻辑直接带过来原生侧通过桥接层对接 OpenHarmony 的能力接口这显然更适合“存量业务快速迁移”的场景。实际做下来这个判断是对的。我们一个十几个页面的视频模块RN 层的页面代码基本没有改动主要工作量都集中在播放器桥接、生命周期适配和播放列表的状态联动上。换句话说选 RN 的核心原因是复用不是因为它比 ArkUI 更高级而是因为我们手里的存量资产在这边。1.2 播放列表需求的边界与痛点播放列表这个功能产品需求拆开来看其实不高视频列表展示、点击某个视频开始播放、播完自动切到下一个、支持列表循环和单曲循环、退出页面后停止播放并记住进度。听起来简单但落到 RN OpenHarmony 这个组合上痛点就出来了。第一OpenHarmony 原生侧的媒体播放能力是有的系统提供 AVPlayer但 RN 侧没有现成封装好的桥接层可以直接用需要自己把原生能力暴露给 JS。第二播放列表涉及“列表数据”和“当前播哪个视频”的联动RN 侧的状态管理要非常清晰否则会出现“列表显示了但不知道当前播的是哪个”“播完报错但不知道哪一步错了”这种问题。第三OpenHarmony 设备的生命周期管理比手机更复杂前后台切换、息屏、系统资源回收任何一个节点没处理干净播放器就会异常。2. 工程初始化与视频播放核心配置2.1 环境准备RN 适配 OpenHarmony 的基本链路OpenHarmony 应用开发先要装好 DevEco Studio下载对应 API 版本的 OpenHarmony SDK。工程结构上RN 适配方案通常是一个聚合工程目录底下既有 OpenHarmony 的原生工程壳用 hvigor 构建对应 .json 配置文件也有 RN 的 JS 业务包node_modules 依赖目录。RN 的运行时本身是 JavaScript 引擎能力OpenHarmony 这边通过 ArkTS 的运行时桥接把 JS 环境和原生模块打通。实操初始化链路大概是这样的创建 OpenHarmony 工程参考 DevEco 的 standard 模板拿到带 Module 的工程结构。在工程里配置 RN 插件依赖包括 react-native 的 OpenHarmony 适配包和 JavaScript 引擎依赖。在工程对应的构建配置里声明项目依赖并指定 RN 应用入口模块。编译出 HAP 包先跑通一个“Hello World”首页确认 JS 层能加载、原生模块能调用。在工程根目录对应配置文件里声明的依赖模块中加入视频播放器的桥接模块。这一步最容易出问题的点在于版本匹配。OpenHarmony SDK 版本和 RN 适配层版本有对应关系版本对不上会出现 JS 引擎起不来、原生模块找不到这类问题。先在小 Demo 上把链路跑通再往里加业务是最稳妥的路线。2.2 视频播放组件的桥接思路视频播放器的桥接是整个方案的技术核心。RN 侧不关心底层是 AVPlayer 还是别的播放器它只想要一个统一的 API传入视频源地址开始播放、暂停、拖动进度、监听播完回调。也就是说RN 侧定义一套播放器接口协议OpenHarmony 原生侧实现这套协议中间通过桥接层做数据转换。OpenHarmony 原生侧的视频播放能力集中在系统提供的播放器上AVPlayer 的状态包括初始化、准备、播放中、暂停、播放完、错误等。桥接工作就是把 AVPlayer 的这些状态映射成 RN 侧能识别的事件RN 侧事件原生侧触发时机传递的数据onLoadAVPlayer 准备完成拿到视频时长duration、naturalSizeonProgress播放进度定时上报currentTime、playableDurationonEnd播放到结尾无或触发者信息onErrorAVPlayer 报错errorCode、errorMsg桥接代码上按原生组件的方式暴露一个 VideoViewRN 侧用组件引用调用播放控制方法。也可以用 TurboModule 的方式暴露全局的播放器管理器但这种场景下按组件封装更贴近视频播放器的使用习惯一个视频视图对应一个播放器实例列表滚动时销毁不可见的实例内存可控。播放器参数映射上RN 侧传过来的典型参数包括 source视频地址、autoplay是否自动播放、loop是否单曲循环、startTime初始进度。这些参数在原生侧转成 AVPlayer 的配置项。注意 OpenHarmony 的 AVPlayer 对视频源的协议支持要确认清楚常规的 HTTP/HTTPS 流和本地文件路径正常特殊协议要提前验证。2.3 权限、生命周期与焦点管理视频应用离不开网络权限。OpenHarmony 工程里申请权限是在对应的模块配置文件里声明的网络权限是最基础的一项。这个配置漏了视频源加载时会直接失败错误信息还不一定好查建议一开始就把权限清单捋一遍。生命周期是播放器功能的大坑。我实现的策略是页面级生命周期回调和播放器状态机联动。应用退后台时如果产品逻辑是暂停播放就在生命周期回调里调用暂停方法回到前台后如果是之前人为暂停的保持暂停如果是因切后台而暂停的自动恢复播放。这里的核心是区分“用户主动暂停”和“系统导致暂停”否则会变成切后台一次回来就乱了。音频焦点也要提一下。如果不处理音频焦点播放视频的同时如果有其他音频应用播放声音会混在一起。OpenHarmony 的音频会话管理能力在原生侧调用通过桥接暴露给 RN 侧。我们的策略是进入播放时申请音频焦点被中断时暂停中断结束后恢复。锁屏界面和控制中心这块如果要做得完整需要原生侧配合做媒体会话元数据上报RN 侧只需要把当前播放标题、进度等数据同步过去即可。3. 播放列表的数据结构与状态设计3.1 列表模型扁平数组和索引是标准答案播放列表的数据结构直接用扁平数组加当前索引不要做得太花哨。我见过有人把“当前播放项”直接用对象存到状态里列表数据一更新整个索引关系就乱了。正确做法是只用 index 指向当前播放项播放对象本身不要在列表数据和当前播放状态里重复维护。一个典型的列表项模型看起来是这个样子interface MediaItem { id: string; // 业务唯一标识 title: string; // 标题 coverUrl: string; // 封面图 videoUrl: string; // 视频源地址 duration: number; // 总时长秒拉流前可以先为0 playProgress: number; // 上次播放进度用于记忆续播 }列表就是一个MediaItem[]当前播放在组件里单独存一个currentIndex。这样列表项要增删、排序、替换都只要操作数组再修正索引即可不会出现“数据源和当前项不一致”的情况。3.2 播放状态机播放模式与索引切换播放状态机的设计我建议做一个串行化的状态转变加载中、可播放、播放中、暂停、播完、失败。不要在暂停和播放之间跳来跳去而不经过状态记录否则会出现“暂停了进度还在走”“播完了点暂停却没反应”这种诡异情况。播放模式一般有四种顺序播放、列表循环、单曲循环、随机播放。用一个枚举表示enum RepeatMode { None, // 顺序播完即停 All, // 列表循环 One, // 单曲循环 Shuffle, // 随机播放 }索引切换的逻辑写成一个 reducer 是最舒服的输入当前索引和播放事件自然播完、用户切换、失败重试输出下一个索引。注意随机播放不能用“每次随机一个数字”的方式要确保不重复播放同一个视频至少连续两次不能一样否则体验极差。3.3 播放进度、缓冲与错误状态进度状态是播放列表里最容易写出“重渲染风暴”的地方。进度条如果每秒回调一次每次回调都直接 setState 整个页面列表会跟着一起重绘卡顿是必然的。我的做法是把进度回调在 RN 侧做一个节流300 到 500 毫秒上报一次并且直接更新到进度条组件内部状态上不经过页面全局状态。缓冲进度要单独跟踪播放器原始回调里有 bufferProgress可播放进度这个和当前播放进度 currentTime 是两回事。进度条组件一般会显示两层一层是已缓冲的灰色条一层是已播放的彩色条。我在桥接层把这两个数据分开传递不要在 RN 侧混成一个数。错误状态这块容易忽略。播放失败的时候如果没有明确的错误态用户会以为视频卡住了。我的方案是维护一个 error 字段失败时显示整页错误提示提供“重试”按钮。重试逻辑不走“直接再播放一次”而是先 reset 播放器到初始状态再重新加载视频源避免在错误状态里连续触发加载导致崩溃。4. 播放列表功能的核心实现4.1 列表 UI 与当前播放项联动列表 UI 我用 FlatList 实现每一项展示封面图、标题、时长和一个播放按钮。点击之后当前播放行高亮图标变成暂停样式其他行保持默认样式。这里的关键是 FlatList 的性能配置和当前项的跟踪方式。FlatList 的配置直接背着不调长列表真的会卡。我用的关键配置FlatList data{mediaList} keyExtractor{(item) item.id} initialNumToRender{6} maxToRenderPerBatch{10} windowSize{7} removeClippedSubviews{Platform.OS android} extraData{this.currentIndex} renderItem{renderItem} /extraData必须传currentIndex否则列表项不会因为当前播放项变化而重新渲染这里是常见的坑。removeClippedSubviews 在视频封面图较多的场景下可以提升滚动性能但要确认封面图不在裁剪后被强制重新加载否则白屏闪烁。点击某一项播放的具体逻辑是这样的const handlePressItem (index: number) { if (index currentIndex) { // 点击当前项切换播放/暂停 togglePlay(); } else { // 切换播放源 stopCurrentPlayback(); setCurrentIndex(index); startNewPlayback(mediaList[index]); } };切换播放源前必须先 stop 当前的播放器顺序不能反过来。我踩过雷先加载新源再释放旧播放器结果是旧播放器回调还在路上新播放器已经初始化完成两个实例互相干扰偶发崩溃。4.2 自动播放下一个与播放模式自动播放下一个触发点是播放器的 onEnd 事件。收到事件之后先根据当前播放模式计算出下一个索引const getNextIndex ( currentIndex: number, total: number, mode: RepeatMode, playedList: number[] ): number | null { if (mode RepeatMode.One) { return currentIndex; // 单曲循环 } if (mode RepeatMode.None) { return currentIndex total - 1 ? null : currentIndex 1; } if (mode RepeatMode.All) { return (currentIndex 1) % total; // 列表循环 } if (mode RepeatMode.Shuffle) { // 从未播放过的项里随机取如果都播过了重置再随机 const unplayed playedList.filter((i) i ! currentIndex); const pool unplayed.length 0 ? unplayed : mediaList.map((_, i) i); return pool[Math.floor(Math.random() * pool.length)]; } return null; };计算出下一个索引后如果不是 null就调用“切换播放源”的逻辑同时把 UI 列表滚动到对应项附近让用户看到正在播哪个。如果已经是最后一个视频且不是循环模式则进入结束态显示“播放列表已播完”此时不能再触发自动连播。还有一个小细节onEnd 事件在某些播放器上存在“重复触发”的问题。我加了防抖逻辑收到 onEnd 后先标记为已处理在下一个事件循环里检查标记防止同一个播完事件触发两次“播下一个”导致索引连续跳两格。4.3 播放器事件监听与状态回写桥接层会把本地播放器的事件抛到 RN 侧RN 侧必须把这些事件和状态机对照起来。我用的是一个精简的事件订阅模式useEffect(() { const subs [ playbackEvent.addListener(onLoad, (data) handleLoad(data)), playbackEvent.addListener(onProgress, (data) handleProgress(data)), playbackEvent.addListener(onEnd, () handleEnd()), playbackEvent.addListener(onError, (data) handleError(data)), ]; return () subs.forEach((sub) sub.remove()); }, [mediaList, currentIndex]);事件回调里我统一通过一个 dispatch 函数更新状态机而不是在各个回调里散着 setState。这样播放列表的任何状态变更都能追踪到调试时打开日志一看就知道现在处于哪个状态、将要变成什么状态。状态回写到 UI 的典型场景是播放按钮的图标切换、进度条的实时更新、当前项的高亮。把这些全部收敛到状态机对应的 selector 里UI 层就很干净。4.4 后台播放与锁屏控制的取舍后台播放这块做之前先确认产品需求是需要退到后台继续播放还是退后台暂停、回前台恢复。两种方案的工作量差别很大。如果只是“退后台暂停、回前台恢复”RN 层处理生命周期回调就够了实现简单且稳定。如果是要求退后台继续播放、支持锁屏控制那就必须原生侧配合做进程保活和媒体会话上报。锁屏界面的上一首/下一首、播放/暂停按钮本质上是在原生侧生成媒体控制事件再通过桥接转发给 RN 状态机。这块要么在 OpenHarmony 原生侧实现全套控制逻辑要么搭一条“原生媒体控制 - JS 状态机处理 - 回原生执行”的消息通道。我的建议是MVP 阶段先把退后台暂停做稳后台续播放到二期。用户对视频应用的核心感知集中在播放列表的连贯性后台播放是体验加分项不应该在初期分散精力。等播放列表整体稳定了再花一个迭代做黑屏下的媒体控制质量会高很多。5. 性能优化与常见问题排查5.1 列表性能FlatList 的参数不是摆设视频列表比纯文本列表更吃性能每一行都有封面图、文字、播放状态三种信息。封面图用尺寸压缩过的图避免直接把大图拉下来显示FlatList 的初始化渲染数量不要设太大屏幕外的地方不用急着渲染。滚动时如果出现明显卡顿优先检查是不是每个列表项都触发了复杂的重新渲染。我在实践中发现很多卡顿并不是 FlatList 本身的问题而是“当前播放项高亮”这个状态让所有行都跟着更新了。优化方法是给列表项的容器组件包一层 memo只让isCurrent变化的那一行重绘。播放器的渲染要独立开。视频画面本身是一个原生视图我把它放在列表之外的区域或者做成全屏模态滚动时视频视图不要嵌在 FlatList 的 item 内部。如果产品要求“列表页内直接有小窗播放”那也要保证小窗播放器是一个浮层而不是跟着滚动条走。5.2 资源释放与内存泄漏播放器的销毁姿势播放列表最容易产生的内存问题是用户退出了页面但播放器实例还在跑事件回调还挂在业务逻辑上。内存被视频解码器、帧缓冲、音视频数据占住长时间不释放就会越走越高最后被系统回收出现“页面一片黑”“应用闪退”。正确的销毁姿势是成对出现的。页面关闭时先停止播放器再释放播放器实例最后移除所有监听器。顺序不要乱尤其是“先移除监听器再停止播放器”会导致停止过程中产生的事件没人处理缺失最后的落点。const cleanup () { playbackEvent.removeAllListeners(); playerRef.current?.stop(); playerRef.current?.release(); playerRef.current null; };我再强调一个细节如果列表页里用户连续点了好几个视频每个视频都创建过播放器实例一定要确保旧实例先释放再创建新的。可以用一个工具函数统一管理播放器实例的生命周期把创建、切换、释放都走同一个入口避免多个播放器实例并存。5.3 常见问题速查表症状可能原因解决方案视频画面黑屏但声音正常视频画面视图与播放器 surface 未绑定在原生侧确认渲染 surface 已附加RN 侧确认视频视图已挂载再开始播放切换视频后偶发崩溃新播放器创建前未释放旧实例统一播放器实例管理先 release 再 init退后台后声音不停止未处理音频焦点与生命周期切换原生侧申请音频焦点并监听前后台生命周期退后台暂停onEnd 触发导致跳两个视频播完事件重复触发未做防抖在事件处理里加标记位防抖后再播放下一个列表滚动严重卡顿FlatList 参数不合理或列表项频繁重渲染优化 FlatList 配置、列表项组件 memo、封面图压缩播放器内存持续增长未在退出页面对放播放器实例或移除监听统一释放播放器清理事件监听视频加载失败但报错信息模糊网络权限缺失或视频地址协议不支持检查权限配置确认视频源协议的兼容性排查技巧上我习惯在桥接层把每个回调的调用时机打点记录包括播放器状态、当前索引、触发原因。播放列表出问题时拿着时序记录一看基本能定位到是“状态没对上”还是“事件没收到”。写在最后的一点实操体会整套播放列表功能从搭建到稳定我感触最深的一点是播放列表的复杂度从来不在播放器本身而在状态流转的一致性。RN 侧管理好 currentIndex、播放模式、播放状态三个核心变量视频列表产品就稳了一大半。配合 OpenHarmony 原生侧做好播放器生命周期和音频焦点的适配整体体验不会比原生实现差。再分享一个细节调试阶段强烈建议在 RN 侧打印状态机的每一次变化包括触发事件、变更前后索引。播放列表这种东西偶发问题大多数是异步时序问题没有完整的日志链很难定位。把这些日志做好后面用户反馈“视频切着切着就卡住了”时你能很快判断出问题是出在业务层还是播放器层。如果你们团队也已经跑通了类似方案欢迎一起交流桥接层的细节尤其是播放器切换这一块各家做法差异比较大值得深入打磨。