React Native for OpenHarmony 列表交互实战：从初始化到性能优化

最近在做一个跑在开源鸿蒙设备上的跨平台应用，业务形态其实很常见：首页信息流、订单列表、消息通知、搜索联想，几乎所有页面都是“列表 + 点击 + 刷新”的组合。团队的前端栈是 React Native，目标平台又多了一个 OpenHarmony，于是我就扎进了 React Native for OpenHarmony 这条链路的选型、适配和排坑里。折腾下来有个挺直观的感受：React Native 社区里成熟的列表交互方案，在鸿蒙侧并不是“开箱即用”，但也远没有到“水土不服”的地步，核心在于搞懂适配层的工作方式，以及知道列表渲染在鸿蒙原生容器上到底是怎么被撑起来的。

这篇文章不聊 SDK API 大全，只围绕“列表交互”这一条主线，把我在 React Native for OpenHarmony 上从工程初始化、列表组件选型、下拉刷新与上拉加载、列表项点击删除，到启动白屏和滚动卡顿排查的完整实践过一遍。代码和配置我会直接给出来，能抄就抄，同时每个关键点后面都会补一句“为什么这么做”。适合正在评估 React Native 跑鸿蒙的团队，也适合准备从 JS 侧接手鸿蒙应用的前端开发者。

1. 为什么要在开源鸿蒙里跑 React Native

1.1 跨平台方案的现实选择

先说结论：如果团队已经深度拥抱 React Native，并且业务复杂度主要在前端状态管理和组件复用上，那 React Native for OpenHarmony 的引入成本是可控的。相比重新用 ArkTS 写一套新 App，跨平台方案能保住的不仅是代码量，更是团队成员已有的心智模型。

我在评估时主要对比了几条路线：一是纯 ArkTS 原生开发，性能和系统能力接入都最理想，但等于给一个新平台单独养一支研发队伍；二是 Flutter 的 OpenHarmony 移植分支，社区也在推进，但团队里没人懂 Dart，短期内不可能上手；三是 React Native for OpenHarmony，也就是社区常说的 RNOH，它对前端开发者来说基本是零门槛迁移，原有的状态管理、网络层、列表组件都能保留。

当然，选型不能只看开发效率。跨平台方案的核心风险在原生能力覆盖度。OpenHarmony 不是 Android，RN 生态里大量第三方原生模块没法直接跑，凡是涉及摄像头、扫码、推送、定位这类能力，基本都要重新看鸿蒙侧的适配情况。我倒不觉得这是拦路虎，因为 RNOH 提供了原生模块注册通道，假装成“中国特色的 JSI 接口”，需要什么自己封装。列表这种高频能力，反而因为组件层级简单，是 RNOH 里成熟度最高的部分之一。

1.2 RNOH 是怎么把 JS 列表变成鸿蒙原生控件的

理解列表交互之前，先要搞清楚 RNOH 的渲染链路。React Native 在 Android/iOS 上有一套成熟的桥接机制：JS 侧描述 UI，原生侧渲染真实控件，中间通过 Virtual DOM 做同步。React Native for OpenHarmony 做的事，就是把这条链路里“原生侧”的实现从 Android/iOS 换成了鸿蒙 ArkUI 组件。

这句话听起来简单，实际工程量不小。JS 侧的 View、Text、ScrollView 等基础组件，需要映射到 ArkUI 里对应的组件或者组件组合上。FlatList 本身不是原生控件，它基于 VirtualizedList 和原生滚动容器工作，所以 RNOH 适配列表时，重点是让 VirtualizedList 的渲染调度、事件回调、滚动监听这些机制，能够接到鸿蒙的原生滚动事件上。

这给我们一个重要的实操提示：列表是否流畅，很大程度上取决于 JS 到原生这层消息通道的效率和原生容器的复用策略。RNOH 在实现上尽量复用了 ArkUI 的滚动和回收机制，所以我们优化列表时，很多 React Native 的老经验依然有效，比如控制单屏渲染数量、避免 renderItem 里创建内联函数、给列表一个稳定的 keyExtractor。后面我会一一展开。

2. 工程初始化与跑通第一个列表

2.1 环境准备：需要的可不只是 Node

React Native for OpenHarmony 的工程和普通 RN 工程有区别。普通 RN 工程直接跑 Android/iOS 壳工程；RNOH 则需要一个鸿蒙壳工程来承载运行时，整体目录结构会更像“RN 业务代码 + harmony 壳”的混合工程。

先列一下我实际准备的环境：

有一个细节容易忽略：DevEco Studio 的 SDK 版本最好和真机系统版本对齐，否则可能出现“API 版本不匹配导致运行时报找不到符号”的问题。我踩过一次坑，模拟器是 API 10，DevEco 里配置的 SDK 却是 API 11，结果列表页启动就崩，日志里全是底层组件解析失败，最后重新对齐 SDK 才解决。

2.2 初始化工程结构

RNOH 的官方脚手架一般会帮我们生成一个典型的双工程结构。项目根目录是我们熟悉的 React Native 工程，package.json、src、index.js 都在这里；另外会生成一个 harmony 子目录，里面是可以被 DevEco Studio 打开的鸿蒙工程。

实际操作时有个常见疑惑：我应该先开哪个？我的习惯是先用命令行把 Metro 跑起来，再开 DevEco Studio 跑 harmony 工程。顺序反过来的话，鸿蒙应用启动时如果发现 Metro 没起来，就会卡在加载 JS Bundle 的环节，表现就是白屏，很容易误判成适配问题。

依赖上，RNOH 的适配包不是靠 npm 自动从 react-native 官方仓库拿到的，需要用社区维护的版本。以当前 release 为例，依赖里会有一个类似 react-native-harmony 的适配包，版本号跟着 RN 主版本走。下面是示意，具体版本号请以当前发布版本为准：

json复制{
  "name": "rnoh-demo",
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.72.13",
    "react-native-harmony": "0.72.13"
  },
  "scripts": {
    "start": "react-native start"
  }
}

安装完依赖后，把 harmony 子目录导入 DevEco Studio，确认 sdk.dir 配置指向了本地 OpenHarmony SDK，就可以联调了。

2.3 先让一个 FlatList 跑起来

绝不要一上来就写复杂交互。第一步永远是“最小可运行列表”，确认渲染链路完整。我通常会准备这样一个页面：

jsx复制import React, { useState } from 'react';
import { FlatList, Text, View, StyleSheet } from 'react-native';

const initialData = Array.from({ length: 50 }, (_, i) => ({
  id: String(i),
  title: `第 ${i + 1} 条数据`,
}));

export default function HomeList() {
  const [data] = useState(initialData);

  return (
    <FlatList
      data={data}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.cell}>
          <Text style={styles.title}>{item.title}</Text>
        </View>
      )}
    />
  );
}

const styles = StyleSheet.create({
  cell: {
    paddingVertical: 12,
    paddingHorizontal: 16,
    borderBottomWidth: StyleSheet.hairlineWidth,
    borderBottomColor: '#e5e5e5',
  },
  title: { fontSize: 16 },
});

这里的 keyExtractor 看上去笨拙，但它是后续一切列表优化的大前提。RNOH 的列表复用机制依赖 key 来识别哪一项发生了增删，key 不稳定会导致渲染错位、点击事件对象张冠李戴。真实项目里如果后端没有稳定 ID，我宁愿让前端拼接一个，也不要直接传 index。

跑通这一步后，列表在鸿蒙设备上能滑动、能渲染，接下来再谈交互才是有价值的。

3. 列表交互能力开发：从下拉刷新到上拉加载

3.1 列表选型：FlatList 还是 SectionList

很多业务列表看起来是“一长串数据”，但内部有分组逻辑。比如订单列表可能要按“待付款 / 已付款 / 已完成”分组，消息中心要按“通知 / 私信 / 系统消息”分组。这时候纠结的不是渲染能力，而是数据结构和头部吸顶需求。

单层无分组的场景，直接用 FlatList，简单、可控、心智负担小。有分组头且头部需要跟随滚动的场景，SectionList 更合适，它天然支持 sections 数据结构，也内置了 stickySectionHeadersEnabled 来控制分组头是否吸顶。

我见到过不少团队用 FlatList 手动拼接分组标题，硬把二维数据压成一维数组。短期能跑，但后续做“分组头吸顶”和“按组收起展开”时，自己维护索引的成本会越来越高。推荐直接用 SectionList：

jsx复制import React from 'react';
import { SectionList, Text, View, StyleSheet } from 'react-native';

const sections = [
  { key: 'doing', title: '进行中', data: [{ id: '1', name: '任务A' }] },
  { key: 'done', title: '已完成', data: [{ id: '2', name: '任务B' }] },
];

function GroupList() {
  return (
    <SectionList
      sections={sections}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <Text style={styles.item}>{item.name}</Text>
      )}
      renderSectionHeader={({ section }) => (
        <Text style={styles.header}>{section.title}</Text>
      )}
      stickySectionHeadersEnabled={false}
    />
  );
}

const styles = StyleSheet.create({
  header: {
    fontSize: 14,
    fontWeight: '600',
    paddingVertical: 6,
    paddingHorizontal: 16,
    backgroundColor: '#f7f7f7',
  },
  item: {
    paddingVertical: 12,
    paddingHorizontal: 16,
  },
});

stickySectionHeadersEnabled 这个参数，Android 和 iOS 的默认行为不同，在鸿蒙上我建议先显式写出来，避免不同版本默认值不一致导致体验漂移。实测中分组头吸顶在 RNOH 上是可用的，但如果你发现吸顶后头部背景透明、文字重叠，通常是没给 header 设置背景色，ArkUI 原生层对透明背景的合成处理跟 Web 不一样，补一个不透明底色就正常了。

3.2 下拉刷新、上拉加载、空态与错误态

列表交互不只是“能点”，更多是数据和用户之间的“对话”。一个生产可用的列表，至少要具备四态：加载中、空数据、加载失败、加载更多。

先处理下拉刷新。RNOH 对 RefreshControl 的适配目前看是到位的，但我不建议直接依赖它作为唯一方案。原因有二：一是不同版本对下拉刷新样式控制能力不一致，二是鸿蒙原生下拉刷新的交互细节（比如触发阈值和回弹动画）跟 iOS/Android 有差异，直接复用 RN 默认样式有时会显得“发飘”。

我的做法是把刷新状态交给 FlatList，刷新逻辑独立封装：

jsx复制const [refreshing, setRefreshing] = useState(false);
const [data, setData] = useState([]);

const onRefresh = useCallback(async () => {
  setRefreshing(true);
  try {
    const latest = await fetchFirstPage();
    setData(latest);
  } catch (e) {
    // 此处应标记错误态，不要默默吞掉
  } finally {
    setRefreshing(false);
  }
}, []);

然后在列表上：<FlatList refreshing={refreshing} onRefresh={onRefresh} />。

这里有个细节：refreshing 只能控制“正在刷新”的转圈状态，真正的数据请求结果状态要自己管理。我见过有人把 refreshing 当成请求锁，结果在返回后 setData 之前又触发刷新，竞态问题就来了。建议所有刷新请求都做“单调递增请求序号”保护，或者用一个 requestIdRef 来判断响应是否过期。

接下来是上拉加载更多。标准做法是 onEndReached + onEndReachedThreshold。onEndReached 在滚动接近底部时触发，onEndReachedThreshold 表示距离底部多少比例时触发，通常设 0.2 到 0.5 之间。

jsx复制const [loadingMore, setLoadingMore] = useState(false);
const [page, setPage] = useState(1);
const [hasMore, setHasMore] = useState(true);

const onEndReached = useCallback(async () => {
  if (loadingMore || !hasMore) return;
  setLoadingMore(true);
  try {
    const nextPage = page + 1;
    const more = await fetchPage(nextPage);
    setPage(nextPage);
    setData((prev) => [...prev, ...more]);
    setHasMore(more.length > 0);
  } finally {
    setLoadingMore(false);
  }
}, [loadingMore, hasMore, page]);

底部加载状态我习惯用一个 ListFooterComponent 来展示，加载中显示一个居中的小菊花，没有更多数据就显示一行“已经到底了”的轻提示。需要注意的是，onEndReached 在列表内容不满一屏时也会触发，可能导致不必要的请求。在 RNOH 上尤其要留意：如果首页数据太少，onEndReached 会连续触发多次，防御逻辑不能只靠 loadingMore 这一个布尔值，还得用 hasMore 兜底。

空态和错误态经常被放最后做，但恰恰是这两个状态最容易引发线上问题。空态要用一个 ListEmptyComponent，里面别只放文案，要放一个“重新加载”按钮；错误态我倾向于不用 ListEmptyComponent，而是单独渲染一个全屏错误页，把重试按钮做明显。因为空态和错误态的用户处置路径完全不同，合并处理会让用户混淆。

3.3 列表项点击、删除与按压反馈

列表项交互里最基础的是点击。RNOH 兼容 TouchableOpacity 和 Pressable，我的建议是直接用 Pressable。原因在于 Pressable 对按压状态的控制更细粒度，而且鸿蒙原生侧对手势状态机的适配，明显是往 Pressable 这套事件模型上靠的。

jsx复制const renderItem = ({ item }) => (
  <Pressable
    onPress={() => handleItemClick(item)}
    style={({ pressed }) => [
      styles.cell,
      pressed && styles.cellPressed,
    ]}
  >
    <Text>{item.title}</Text>
  </Pressable>
);

这里有一个 Easy 踩坑点：style 函数如果直接写在 JSX 里，每次 render 都会创建新函数，列表项一多，React 会频繁重渲染。我通常会把它抽成 renderItem 并使用 useCallback，组件内部再用 React.memo 包一下。

删除操作上，我建议先做“点击删除按钮 + 二次确认”，再考虑做侧滑删除。不是侧滑不好，而是侧滑涉及手势冲突，在 RNOH 上对 PanResponder 和原生滚动容器的响应链调优比较费时间。如果产品上一定需要侧滑，有一个替代思路：列表项右侧常驻一个“更多”按钮，点击后弹出 ActionSheet 或半屏菜单，菜单里提供删除、置顶等操作。这个方案跨平台一致性高，也完全绕开手势冲突。

还有一个列表项交互容易出错的地方是“点按水波纹”。android_ripple 在 Android 上有效，但在鸿蒙上不一定能映射到相同的涟漪效果。我给鸿蒙这边准备了一个 fallback：按压时改变背景色，属于最朴素但最稳定的反馈方式，不要为了效果一致去硬调 ArkUI 的 Ripple 参数。

3.4 列表项与原生能力协作：一个相机场景示例

列表交互不只是列表内部的滚动和点击，经常还要和原生能力联动。举个例子：消息列表里有一个“拍照上传”入口，点击后要拉起鸿蒙原生相机，拍完把图片 URL 回传到列表里并追加一条记录。

这类能力在 RNOH 上不能直接使用 RN 生态里现成的 react-native-image-picker，因为底层依赖 Android 原生实现。正确姿势是自研一个鸿蒙原生模块，在 ArkTS 侧调用系统拍照能力，然后把结果通过回调传给 JS。

示意代码如下，JS 侧约定名为 OpenHarmonyCamera：

js复制import { NativeModules } from 'react-native';

const CameraModule = NativeModules.OpenHarmonyCamera;

async function handleTakePhoto() {
  try {
    const uri = await CameraModule.takePhoto();
    // 拿到 uri 后追加到列表数据中
    appendToList({ type: 'photo', uri });
  } catch (e) {
    // 用户取消或权限不足
  }
}

这个方案的重点是原生模块的 Promise 回调要处理好“取消拍摄”和“权限拒绝”两个分支。很多崩溃不是主流程问题，而是用户点了一次取消后，回调带着 errorCode 返回 JS，JS 侧没有处理，导致 Promise 一直挂起，列表后续的状态更新全部失效。

另外，NativeModules.OpenHarmonyCamera 调用失败时，如果 JS 侧直接解构使用，会碰到 undefined 属性问题。稳妥做法是先判断 CameraModule && typeof CameraModule.takePhoto === 'function' 再用，不然鸿蒙 App 在这个模块没注册时，白屏或崩溃会让调试成本翻倍。

4. 实战中的白屏、卡顿与点击失效排查

4.1 启动白屏：别急着怀疑适配层

React Native 启动白屏这个话题，带着“鸿蒙”前缀后显得特别吓人，其实大部分原因跟普通 RN 工程一样，甚至更简单。

Debug 模式下的白屏，第一嫌疑就是 Metro 没有起来或者鸿蒙应用连不上 Metro。回顾一下我前面强调的启动顺序：先开 Metro，再用 DevEco Studio 运行 harmony 工程。如果鸿蒙应用启动时连不上打包器，它只能停留在空白根视图，这种白屏在 logcat 里通常能看到 bundle URL 连接失败。

第二嫌疑是权限。HarmonyOS 应用访问网络需要在 module.json5 里声明 ohos.permission.INTERNET。Debug 模式加载 bundle 走的是局域网 HTTP 请求，这个权限没开，Metro 再正常也白搭。这个坑非常隐蔽，因为应用本身不崩溃，就是白屏，日志里报的还不一定是权限错误。

第三嫌疑是入口容器高度为 0。有些工程把 RN 的根视图嵌在原生页面的某个 ViewGroup 里，如果外层容器没有撑满，RN 渲染出来的页面高度就是 0，表现同样是白屏或空白一块。检查方式很简单：给根容器设固定高度或者 flex: 1，至少能快速排除。

Release 模式下的白屏，则多半是 bundle 资源没有正确打包进鸿蒙应用。RNOH 工程里 JS bundle 的产物路径和 Android 的 assets 目录不同，需要按文档把 bundle 放到鸿蒙工程指定的资源目录。我遇到过一次 Release 包白屏，最后发现是资源被打进了 media 目录但路径大小写写错了，DevEco Studio 编译时不校验，运行时找不到文件才暴露。

4.2 列表卡顿与白屏排查：从 React 侧到鸿蒙原生侧

列表渲染顺畅与否，我习惯先从 React 侧找原因，因为那是我们能直接控制的部分。

最常见的卡顿元凶是 renderItem 里写了内联函数和匿名组件。每调用一次 renderItem 都会重新创建函数，列表项一多，React 的 diff 成本指数上升。在 RNOH 上，开发体验和 Android 几乎一致，所以这条优化必须做。

第二个元凶是 item 组件没有做 memo。很多 item 包含图片、状态按钮、子列表，这些组件的 props 如果每次都生成新对象，即使数据没变，也会触发重渲染。用 React.memo 包一层，能显著降低列表滚动时的 JS 线程压力。

第三个元凶是把 FlatList 嵌进了同一个方向的 ScrollView。这在 RNOH 上报错可能不像 Android 那么明显，但现象就是滚动到某个位置后整个页面掉帧。解决方案一是不要用这种嵌套结构，二是把外层改成普通 View，让 FlatList 自己处理滚动。

如果 React 侧优化都做了，仍然卡，那就要考虑是不是触发了“白屏滚动”问题。这个现象在 Android 的回收机制里见过，鸿蒙侧也存在类似的回收策略。表现是快速滑动列表时，尚未渲染的 item 区域显示为空白，滑到那里才慢慢补上内容。不是数据渲染失败，只是列表窗口回收了不可见节点。

应对思路有这么几条：

getItemLayout 对固定行高的列表几乎是无损优化。示例：

jsx复制const ITEM_HEIGHT = 56;

getItemLayout={(_, index) => ({
  length: ITEM_HEIGHT,
  offset: ITEM_HEIGHT * index,
  index,
})}

这样列表就可以直接根据 offset 计算当前渲染窗口，不需要等每一项的 onLayout 结果，滚动时白屏概率会小很多。但如果你的 Item 包含图片异步加载导致高度不确定，强行用 getItemLayout 反而会出现内容错位，要用得谨慎。

4.3 点击失效和滚动冲突的排查现场

列表点击失效是我在 RNOH 上遇到过的独特问题。现象很怪：列表能滚动，长按也有反馈，就是单击没反应。

后来定位到原因，不是 RN 层事件丢了，而是我的 Pressable 里同时用了 onPress 和 onLongPress，并且长按手势的延迟阈值和鸿蒙原生滚动容器的识别产生了竞争。在 Android 上这种组合很常见，但在鸿蒙侧，长按识别会占用更长的触摸事件时间，导致快速点按时系统判定为“未命中小手”，事件被吞掉。

排查思路是这样的：先删掉 onLongPress 看点击是否恢复。如果恢复，说明手势竞争；如果没恢复，再看 Pressable 的外层是否被一个透明绝对定位 View 遮挡。第三排查项是 zIndex，有时为了显示浮层，给某个 View 设了很大的 zIndex，结果它盖住了列表项，点击全被它吃掉。

滚动和点击同时存在的页面，我的经验法则是“能交给原生滚动容器的，不要自己拦截手势”。比如 iOS 上常用的 onScroll 做导航栏渐变效果，在鸿蒙侧可以继续用，但一定要设 scrollEventThrottle，否则每帧都回调会把 JS 线程打满，点击响应自然就变慢了。

再补一个排查技巧：RNOH 的调试日志不一定从 DevTools 里能看全。遇到交互类 bug，尽量在鸿蒙设备上用 DevEco Studio 的 Log 窗口过滤 Rnoh、ReactNative 关键字，很多原生侧的事件分发信息和 ArkUI 渲染日志都埋在这里，比单纯看 React DevTools 有用得多。

5. 从列表出发，再给几条落地建议

整个实践做下来，我对 React Native for OpenHarmony 的态度是“可用，但要有耐心”。它不是一个能完美平替 Android/iOS 的跨平台方案，但如果你主要在列表、表单、状态管理这类 CRUD 业务里打转，它确实能帮团队省掉大量重复工作。

如果让我给三个最想强调的建议：第一，先把最小列表跑通再优化，RNOH 的层级多了之后，定位问题的链路会变得很长，最小可运行工程能帮你快速区分“JS 层问题”和“鸿蒙原生层问题”；第二，列表性能优化的黄金组合是稳定 key + React.memo + getItemLayout，这三板斧能解决八成以上的滚动卡顿；第三，遇到交互异常时，不要只盯着 JS 代码，多看看原生日志，RNOH 事件链路是跨层的，问题常常藏在 JS 和 ArkUI 的握手间隙里。

我自己的下一步是把列表预排序、大批量数据分页加载、以及复杂列表项的嵌套滚动再压一压性能。这类能力在 Android/iOS 上已经有成熟的性能基线，但在鸿蒙上还需要结合真机实测来调参。如果你也在踩同样的坑，建议手边常备一台真机，模拟器的滚动帧率和触摸采样跟真机差太多，最终的优化结果一定要以真机为准。