React Native鸿蒙跨平台入门：温度计Demo实战指南

先说结论：如果你已经会 React，想试试鸿蒙端的跨平台开发，做一个温度计 Demo 是性价比最高的入门方式。它不涉及复杂业务，却能把你从“React Native 能不能跑在鸿蒙上”一直带到“跑起来之后怎么调试、怎么排查白屏、怎么处理状态更新”这条完整链路，而且整个过程不需要碰原生代码。下面就是我实际跑通这个项目后整理的全过程。

我选择“React Native + 鸿蒙跨平台”这个方向，并不是因为它能替代所有原生方案，而是因为现在 React Native 的跨端能力已经天然覆盖了 Android、iOS，再加上社区维护的鸿蒙适配层，一套 JS 代码就有机会在三种系统上复用。对个人开发者来说，这意味着可以少写两套 UI，把精力留到业务逻辑上。对团队来说，几套端上代码合并成一套，维护成本会明显降下来。当然，前提是你先接受“RN 业务层 + 原生宿主”这种架构思路。

下面从项目设计、环境搭建、温度计实现、鸿蒙端部署、常见问题五个部分展开。整个内容都是我实际敲过、跑过、翻过车的记录，不是纸面教程。

1. 项目整体设计与思路拆解

1.1 为什么选温度计作为入门案例

温度计这个场景，几乎把 React Native 入门必学的知识点都覆盖了：

• 组件树：需要用到 View、Text、StyleSheet 这几个最基础的组件。
• 状态管理：温度值本身就是动态状态，天然适合用 useState 保存。
• 生命周期与副作用：模拟传感器持续上报温度，必须用 useEffect + setInterval。
• 样式计算：温度条高度、滑块位置、颜色变化，都需要按数值动态计算。
• 跨端验证：同一个组件，在 Android 上能跑，在鸿蒙上也能跑，这就是跨平台开发最直接的体感。

做个温度计，而不是做 Todo List，是因为温度计比 Todo List 更接近真实业务场景——真实业务里几乎处处是“动态数据驱动界面变化”。Todo List 多数时候是静态列表，你感受不到“状态一改，整个 UI 跟着变”的紧张感。温度计则每秒钟都在变化，这能逼着你理解 React 的渲染机制。

1.2 React Native 和鸿蒙的结合方式

很多人第一次听到“React Native 鸿蒙跨平台”会以为是把 React Native 直接装进鸿蒙系统，其实不是。准确说法是：鸿蒙（OpenHarmony 系）这边有一个 React Native 的适配运行时，它把 RN 的 JS 层和鸿蒙的 ArkUI 组件层桥接起来。你在 JS 里写的 View，最终渲染出来的是鸿蒙原生的组件；你在 JS 里管理的 state，最终会以 ArkUI 的属性更新方式同步到界面上。

打个比方：React Native 像是有一套“通用 UI 翻译标准”，Android 负责翻译成 Android 的 XML，iOS 翻译成 UIKit，鸿蒙这边就翻译成 ArkUI 的组件结构。温度计这个 Demo 的所有界面代码都只用英文（JS 语法）写一遍，然后分别交给不同的“翻译官”。

社区里目前维护的鸿蒙适配层项目，一般叫react-native-harmony这个方向。它支持通过特定模板初始化鸿蒙工程，也能把现有 RN 工程“接”到鸿蒙宿主应用里。入门阶段不推荐碰原生桥接，先把 JS 层的组件、状态、样式用熟，后面再深入性能调优和自定义原生模块。

1.3 技术选型为什么要这么定

我的建议组合是：React Native 0.72 或 0.73 版本的稳定分支 + HarmonyOS SDK（API 9 以上）+ TypeScript。原因有三个：

第一，0.72 / 0.73 是社区适配鸿蒙时覆盖比较成熟的版本范围，老版本不一定有对应的鸿蒙适配产物；第二，TypeScript 能帮你提前发现温度计算、样式属性这些数据类型错误，尤其对新手特别友好；第三，API 9 以上的鸿蒙模拟器和真机生态比较完整，不至于卡在环境问题上。

有一点要提醒：React Native 的社区生态和鸿蒙适配层的版本是深度绑定的，不要自己随便升级 SDK 或 RN 大版本。我见过不少项目跑不起来，都是因为用了太新的 React Native 版本，而鸿蒙适配还没有跟上，最后只能降级。选型的时候优先看适配仓库里明确标注的“支持版本范围”，而不是追新。

2. 环境准备与工程初始化

2.1 你本地需要准备哪些东西

先把工具链列出来，省得你一边装一边缺：

• Node.js 18 或 20 的 LTS 版本，React Native 的脚手架和 Metro 打包器都依赖它。
• JDK 17，RN 0.73 之后默认要求 JDK 17。
• Android Studio（可以不装，但装了方便你先在 Android 上验证工程是否正常）。
• DevEco Studio，这是鸿蒙侧的 IDE，用来打开鸿蒙工程、连接模拟器或真机。
• 鸿蒙 SDK（API 9 以上）和对应的模拟器镜像。

装完之后，先执行：

node -v npm -v java -version

确认这三个命令都有输出，再往下走。工程初始化阶段最忌讳一件事：环境变量没配好，然后报一个看不懂的错，先在环境上耗掉一下午。

2.2 初始化 React Native 工程并接入鸿蒙适配

我实际操作时，用的是社区提供的鸿蒙模板来初始化工程，这样最省事。

npx @react-native-community/cli init RNThermometer --version 0.72.7 cd RNThermometer

如果你的 CLI 版本较新，也可以直接用npx react-native init。初始化之后，这个工程默认是能跑 Android 和 iOS 的。先别急着加鸿蒙，先在 Android 模拟器上跑一遍，确认 React Native 基础链路没问题。这一步非常重要，因为后面如果跑鸿蒙出现问题，至少有 Android 作为对照，能快速判断是业务代码问题还是鸿蒙适配问题。

确认 Android 能跑起来之后，再按鸿蒙适配仓库的说明，把鸿蒙宿主工程相关文件导入进来。不同适配方案的操作有点差异，我用的流程是：把harmony目录放到工程根目录下，然后在 DevEco Studio 里打开这个harmony目录作为鸿蒙工程，再把 RN 生成的 JS Bundle 打包进鸿蒙应用里。

这里有一个关键的工程结构认知：鸿蒙端本质上是一个“壳工程”，它的职责是加载 JavaScript Bundle，并提供一个原生环境给 RN 渲染。温度计的业务代码全部在 JS 层，鸿蒙壳工程里几乎不需要改逻辑。

2.3 依赖安装的注意事项

初始化好之后，需要安装基础依赖：

npm install

如果你的项目网络环境访问 npm 官方源比较慢，可以用你所在公司或团队内部配置的 npm registry，这里不展开。关键点是：安装鸿蒙适配相关依赖时，要以适配仓库文档中指定的包名为准，不要自己从 GitHub 上随便拉一个分支来用。

踩坑提醒：安装依赖之后，最好固定住package-lock.json，不要频繁执行npm install覆盖依赖版本。React Native 加鸿蒙适配的依赖树非常敏感，稍有不慎就会把某个原生模块版本搞乱，导致编译期或者运行期报一堆莫名其妙的问题。

3. 温度计界面实现：从状态到 UI 的完整链路

3.1 界面结构设计

温度计的 UI 我拆成了四个部分：

1. 温度数值显示，一个大号的 Text。
2. 温度条，一个垂直方向的“水银柱”，内部高度随温度变化。
3. 温度刻度，用于展示当前温度范围。
4. 一个滑块标记，标出当前温度对应的位置。

这四部分全是纯 JS 组件，没有任何自定义原生模块。整个界面放在一个View里，通过StyleSheet.create管理样式。这样做的好处是：如果你之后想把这个 Demo 扩展成湿度计、气压计，只需要改数据源和样式，不用动工程结构。

3.2 用 useState + useEffect 模拟传感器温度

温度计的灵魂在“数据不断变化”。真实硬件是通过传感器拿到温度，这里我用setInterval模拟一个温度变化过程：每 800ms 更新一次温度，数值在 15 到 45 摄氏度之间浮动，并且每次变化幅度控制在 ±1 度以内，这样显示起来更自然。

import React, { useEffect, useState } from 'react'; import { StyleSheet, Text, View } from 'react-native'; const MIN_TEMP = 15; const MAX_TEMP = 45; export default function Thermometer() { const [temperature, setTemperature] = useState(26); useEffect(() => { const timer = setInterval(() => { setTemperature(prev => { const step = Math.random() * 2 - 1; const next = prev + step; if (next < MIN_TEMP) return MIN_TEMP; if (next > MAX_TEMP) return MAX_TEMP; return Math.round(next * 10) / 10; }); }, 800); return () => clearInterval(timer); }, []); return ( <View style={styles.container}> <Text style={styles.tempText}>{temperature.toFixed(1)}°C</Text> <Text style={styles.statusText}>当前温度</Text> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#f5f5f5', }, tempText: { fontSize: 72, fontWeight: 'bold', color: '#333', }, statusText: { fontSize: 16, marginTop: 8, color: '#777', }, });

代码里面有几个细节值得说明：

• setTemperature用了函数式更新，因为下一次温度依赖上一次温度。如果你直接在外面读temperature然后加上一个随机数，容易在定时器多次触发时读到旧值，出现温度跳动异常。
• setInterval的清理函数一定要写。这个组件一旦卸载，定时器不清理，就可能在页面关闭后继续触发状态更新，轻则警告，重则崩溃。
• 温度保留一位小数，这样显示更有体温计的真实感。Math.round(next * 10) / 10是常见的保留一位小数写法，避免直接用toFixed丢失数字类型精度。

3.3 温度条和滑块：动态百分比计算

接下来是核心视觉效果：一个竖条，内部填充高度根据温度变化而变。先把整个温度范围 15~45 映射到 0%~100%。

const percent = ((temperature - MIN_TEMP) / (MAX_TEMP - MIN_TEMP)) * 100;

这个百分比就是温度条内部填充区的高度，也是滑块纵坐标的位置依据。滑块我用了一个绝对定位的小圆点，通过bottom属性控制位置：

<View style={styles.thermoBody}> <View style={[styles.thermoFill, { height: `${percent}%` }]} /> <View style={[styles.thermoMarker, { bottom: `calc(${percent}% - 8px)` }]} /> </View>

注意：React Native 的样式里，百分比写法在不同版本上的支持程度不一样。height: '50%'这种是支持的，但calc()支持力度一般。为了稳妥，滑块位置我用绝对定位加偏移量计算成具体像素值，而不是直接塞一个calc()进去，否则可能在 Android 上没问题，到了鸿蒙上就解析不了。

算像素的做法是：先给温度条一个固定高度THERMO_HEIGHT = 260，然后：

const markerBottom = (percent / 100) * THERMO_HEIGHT - 8;

8 是滑块半径的一半，这样滑块的圆心刚好对准当前温度位置。

3.4 温度颜色渐变：用简单函数映射

温度计还有一个细节是温度条颜色，冷的时候是蓝色，热的时候是红色。我写了一个函数，根据温度在范围内的位置，把 RGB 值从蓝色渐变到红色：

function getColor(percent: number) { const r = Math.round((percent / 100) * 255); const g = Math.round(80 + (1 - Math.abs(percent - 50) / 50) * 100); const b = Math.round(255 - (percent / 100) * 255); return `rgb(${r}, ${g}, ${b})`; }

这个函数很基础，但已经足够模拟“低温蓝、高温红”的直觉感受。实际项目里，颜色映射可以做得很复杂，比如引入色板库，但入门阶段手动算 RGB 能帮你理解：界面上的任何视觉变化，本质上都是数据到样式的映射。

3.5 完整组件拼装

把所有部分拼在一起，完整组件看起来类似这样：

export default function Thermometer() { const [temperature, setTemperature] = useState(26); // ... useEffect 部分省略 const percent = ((temperature - MIN_TEMP) / (MAX_TEMP - MIN_TEMP)) * 100; const markerBottom = (percent / 100) * THERMO_HEIGHT - 8; const currentColor = getColor(percent); return ( <View style={styles.container}> <Text style={[styles.tempText, { color: currentColor }]}> {temperature.toFixed(1)}°C </Text> <View style={[styles.thermoBody, { height: THERMO_HEIGHT }]}> <View style={[ styles.thermoFill, { height: `${percent}%`, backgroundColor: currentColor }, ]} /> <View style={[styles.thermoMarker, { bottom: markerBottom }]} /> </View> <View style={styles.scaleRow}> <Text style={styles.scaleText}>{MIN_TEMP}°</Text> <Text style={styles.scaleText}>{MAX_TEMP}°</Text> </View> </View> ); }

界面做完之后，先在 Web 端或者 Android 模拟器上跑一遍，确认界面长这样：温度数字够大，竖条高度随温度变化，滑块跟着上下动，颜色从蓝渐变到红。这部分验证通过，再进入鸿蒙端部署环节。

4. 鸿蒙端部署与调试：从“能跑”到“跑顺”

4.1 把 JS Bundle 打包进鸿蒙应用

React Native 在开发阶段通常依赖 Metro dev server，也就是说手机要从电脑上拉取 JS Bundle。这种方式在调试期很方便，但到了鸿蒙真机上，如果电脑不在身边，或者网络不通，应用就会一直白屏。所以部署到鸿蒙之前，我先用打包命令把 JS Bundle 生成出来：

npx react-native bundle --platform harmony --dev false --entry-file index.js --bundle-output harmony/entry/src/main/resources/rawfile/index.jsbundle --assets-dest harmony/entry/src/main/resources/rawfile

注意这里--platform harmony是鸿蒙适配层认识的自定义平台标识，如果命令不支持这个参数，说明适配层版本或方式不对，需要看看对应模板的文档。

Bundle 打出来之后，启动鸿蒙应用时会直接加载rawfile里的 JS Bundle，不依赖 Metro。这样应用在真机上也能正常启动，不会出现“连不上开发服务器”的白屏。

4.2 DevEco Studio 构建与运行

用 DevEco Studio 打开工程里的harmony目录，等待它同步依赖，然后选择鸿蒙模拟器或真机运行。这里有几个我实际遇到的情况：

• 鸿蒙模拟器目前对 host 平台有要求。我当时用的模拟器镜像只支持 arm64 架构的设备，后来改用真机测试，反而更稳定。
• 构建过程如果报“SDK 版本不匹配”，去 DevEco 的 SDK Manager 里确认 API 版本是否和工程配置一致。
• 第一次构建时间会比较长，主要花在下载依赖和编译原生壳工程上，耐心等，不要中途关闭。

运行成功之后，你会看到鸿蒙应用里出现和 Android 一模一样的温度计界面，温度持续刷新，滑块和颜色跟着变化。这一刻你就已经把 React Native 的跨端能力真正落到了鸿蒙设备上。

4.3 真机调试常用的日志命令

如果应用跑起来之后界面没有正常显示，或者温度不刷新，最直接的办法是看日志。我用hdc连接真机，查看应用输出：

hdc shell hilog | grep ReactNativeJS

鸿蒙的日志系统叫hilog，React Native 运行时的 JS 日志会打到这里。看到类似Running "RNThermometer" with rootTag这样的输出，说明 JS 运行时已经正常启动。如果什么都没有，大概率是 Bundle 没加载对，先把工程配置和打包路径再检查一遍。

5. 常见问题与排查技巧实录

5.1 React Native 启动白屏

白屏是新手遇到最多的现象，几乎可以排进“RN 鸿蒙开发劝退三连”。我自己的排查顺序是：

1. 看 Metro 是否启动。开发模式下，应用必须能访问开发服务器，如果手机和电脑不在同一网络，或者端口被占用，就会白屏。最简单的验证办法是把 JS Bundle 打包到本地，然后重新安装应用。
2. 看日志里有没有报 JS 异常。比如组件里某个属性写错、某个 API 在鸿蒙适配层还不支持，都会导致渲染失败白屏。
3. 检查入口文件。index.js里注册组件名的字符串，必须和应用宿主启动时要求的名称一致，大小写都不能错。

5.2 模拟器运行失败或无法安装

如果你用鸿蒙模拟器，报“运行设备不兼容”或者“只能在 arm64 平台运行”，不用慌，这是模拟器镜像对宿主架构的限制。解决思路有两个：换一台 arm64 的电脑跑模拟器，或者直接用鸿蒙真机调试。我当时的机子是 x86_64，模拟器直接没法用，切到真机之后一次就跑通了。

5.3 温度不刷新或 UI 卡住

如果界面静态显示，温度不变化，大概率是setInterval没有生效，或者 JS 线程被卡住。先确认useEffect有没有正确注册定时器，再看日志有没有Warning: Can't perform a React state update on an unmounted component之类的警告。如果是后台运行导致定时器被挂起，可以把模拟传感器数据的逻辑改成一次性生成一组数据循环播放，这样至少能看到界面变化。

5.4 鸿蒙构建阶段报错速查

我把最常见的几个构建错误整理成一张表，方便你对照：

5.5 独家避坑：千万别忽略锁版本

这个项目踩过最大的坑，是依赖版本不一致。React Native 本身迭代快，鸿蒙适配层的发布节奏很难完全跟上。我之前试着把 RN 从 0.72 升到 0.73，结果鸿蒙壳工程里有一个原生组件无法编译，整个项目卡了两天。后来老老实实把版本降回适配层支持的区间，一次通过。

所以我的建议是：把这个温度计 Demo 当做一个“冻结版本”的项目，所有关键依赖都用精确版本号锁死，不要随手npm update。等这个项目跑顺了，再另外开分支升级版本，验证完再合入，这才是稳妥的玩法。

最后说一点个人体会。这个温度计 Demo 看起来很小，但跑通之后，你对 React Native 的“状态驱动 UI”会有更深的肌肉记忆：温度数据一变，温度条高度跟着变，滑块位置跟着变，颜色跟着变，这些变化不是靠手动操作 DOM 实现的，而是 React 声明式渲染在替你干活。做鸿蒙跨平台开发也是这样，重要的不是会写多少语法，而是理解数据在 JS 层和原生层之间怎么流动。把这条链路打通，以后不管换什么业务、什么设备，你都不会慌。

如果你把温度计跑通了，下一步可以试试给温度计加一个“最高温/最低温”记录，或者接入真实传感器数据。这个方向练下来，你会把 React Native 的列表渲染、组件通信、原生模块调用都补齐，那时候你已经不是入门选手了。