这两年做React Native开发的同学,基本都绕不开鸿蒙。react-native-harmony(大家习惯叫RNOH)从最早的尝鲜版本到现在,已经能稳定承接不少业务页面了。但真正把项目迁到鸿蒙上之后你会发现,RN那套生态里的好东西,像TanStack Query(React Query)这种纯JS/TS数据层方案,是可以直接平移过来的,配合无限滚动列表,体验做出来相当顺滑。
这篇文章不聊虚的,就围绕“React Native鸿蒙版 + React Query无限滚动”这套组合,从环境准备、useInfiniteQuery的核心机制、完整代码实现,到鸿蒙端特有的坑和排查思路,一次性讲透。适合正在做RNOH迁移的团队,也适合准备在鸿蒙上从零搭建列表类应用的同学参考。
1. 整体设计与思路拆解:为什么这套组合值得用
1.1 鸿蒙端RN应用的数据层选型
先说说我为什么在鸿蒙版项目里坚持用React Query,而不是回到redux + saga那一套老路上。RNOH是基于React Native官方框架的鸿蒙适配分支,它的特点在于:JS层代码几乎不用改,原生侧由OpenHarmony的C++/ArkTS实现桥接。这意味着你在RN生态里积累的纯逻辑库,比如axios、React Query、dayjs,都可以继续用。
React Query在鸿蒙端带来的核心价值有三个:
- 自动管理服务端状态缓存,列表页来回切换不重新发请求
- 请求去重,多个组件同时依赖同一份数据时,只发一次请求
- 无限滚动开箱即用,useInfiniteQuery帮你维护分页数据和加载状态
相比redux-thunk/saga那一套,React Query不需要你手写action、reducer、selector的流水线,对鸿蒙这种需要快速迭代的业务场景非常友好。而且它不依赖任何原生模块,纯TypeScript实现,RNOH环境跑起来没有任何额外适配成本。
1.2 无限滚动的常见技术路线
做无限滚动列表,业内主流有三条路:
- 手动维护page状态 + FlatList的onEndReached回调,自己拼数组、自己处理loading和error
- 用useInfiniteQuery自动管理分页数据,配合FlatList的onEndReached触发fetchNextPage
- 用FlashList这类高性能列表组件 + 自封装分页hook
第三条对鸿蒙RNOH来说暂时不太现实,因为FlashList依赖原生代码,而RNOH的第三方原生组件生态还没有那么全。第一条太原始,代码里到处是setState和useEffect,页面复杂以后很难维护。
所以我选了第二条。useInfiniteQuery把分页加载、缓存、重试、数据拼接都封装好了,我们只需要提供getNextPageParam函数告诉它“下一页怎么取”就行。这种声明式的写法,特别适合鸿蒙上那种页面逻辑复杂但开发周期又紧的场景。
1.3 整页结构拆解
一个完整的无限滚动页面,拆开来看其实就四层:
| 层 | 职责 | 对应实现 |
|---|---|---|
| API层 | 定义请求函数和返回类型 | request.ts |
| Hook层 | 组合React Query的useInfiniteQuery | useArticleList.ts |
| UI层 | FlatList渲染 + 加载触发 | ArticleListView.tsx |
| 状态层 | 缓存、过期、持久化 | React Query Client配置 |
这样分层的最大好处是:UI层只关心数据和回调,完全不碰请求逻辑;Hook层只关心数据获取策略,不关心页面长什么样。后面鸿蒙端出了兼容性问题时,你可以精准定位到底哪一层出了问题,不用从头到尾翻代码。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备:RNOH工程里接入React Query
2.1 版本选择是第一道坎
RNOH的版本和RN官方版本是错位对应的,不要随便装。以react-native-harmony目前最稳定的0.72.x分支为例,它对应的就是React Native 0.72.10。装依赖的时候一定要保持这个对应关系,否则会出现原生侧接口对不上,编译都过不了的情况。
我自己用的是一套经过验证的组合:
bash复制react-native: 0.72.10
react-native-harmony: 0.72.20
@tanstack/react-query: ^5.51.0
react-native-safe-area-context: 4.10.0(鸿蒙适配版)
React Query装的时候留意一下peerDependencies,它要求react >= 18,RN 0.72默认就是React 18.2.0,没问题。
2.2 安装与工程初始化
创建RNOH工程有两种方式:一是直接clone官方脚手架模板,二是在现有RN工程里通过替换依赖的方式接入鸿蒙。如果你是从零开始,推荐用脚手架:
bash复制npx @react-native-community/cli init RNHarmonyDemo --version 0.72.10
cd RNHarmonyDemo
