企业官网建设流程全解析

一次从白屏爬出来的鸿蒙React Native实战

第一次把React Native工程往鸿蒙手机上搬的时候，我卡在最前面的启动白屏上整整一个晚上。那种感觉特别拧巴：明明在Android模拟器上跑得欢，到鸿蒙设备上却只能看到一个白色屏幕。

后来一步步排查发现，问题基本不在RN这套框架本身，而在鸿蒙环境的接入方式和工程配置的细节上。把这些问题捋顺之后，整个开发体验其实相当顺畅，日常写UI、调样式、跑真机调试，跟写普通RN几乎没有区别。这篇东西就是给打算入坑“React Native + 鸿蒙”跨平台开发的小白准备的，从环境搭建讲到真正上手实现多种文本装饰效果，把那些文档里不会写的坑都摊开来说清楚。

文本装饰看起来是个小功能，但它非常典型：涉及React Native的Text组件、样式系统、平台适配，还牵扯到真机渲染差异。啃完这一条线，你对RN在鸿蒙上怎么工作、怎么调试、怎么排错，会有一个整体认知，后面再做复杂页面就顺手多了。

1. 为什么小白要选“RN + 鸿蒙”这条路线

1.1 鸿蒙生态现状与RN的定位

鸿蒙系统这几年的设备覆盖量已经非常大，手机、平板、电视、智能座舱都在同一个生态里。对开发者来说，这意味着一个应用只要能在鸿蒙上跑起来，触达的终端范围比单纯做Android、iOS要广不少。

但现实问题是，原生鸿蒙开发用的是ArkTS + ArkUI，虽然语法上跟TypeScript很像，但组件模型、状态管理、布局思路跟React完全是两套体系。让一个已经熟悉React生态的开发者去切换心智模型，成本并不低。

React Native的价值恰恰在这里：它能让前端/RN开发者用已经熟悉的React组件模型去写鸿蒙应用，同时保持跨Android、iOS、Web等多端复用的能力。鸿蒙只是RN支持的目标平台之一，理论上你写的业务逻辑和大部分UI样式能在多个平台复用，省掉整套重复开发的成本。

1.2 这套方案适合谁，能解决什么问题

如果你是下面几类人，这条路非常值得尝试：

• 已有RN项目但想覆盖鸿蒙用户：最简单粗暴的需求，直接做平台适配，让一套代码跑多个系统。
• 前端转移动端的开发者：你懂React，但不想学两套原生开发。RN的鸿蒙适配方案让你的技能直接平移到鸿蒙。
• 学生或独立开发者：想低成本验证一个多端产品，短短几天内产出能跑的手机应用，不需要去啃深奥的系统底层。

当然，它不适合所有场景。比如你的核心功能大量依赖系统级API、传感器或者极高性能的图形渲染，那还是老老实实走原生ArkTS路线。但对于绝大多数信息展示、表单管理、数据交互类应用，RN在鸿蒙上的表现完全够用。

2. 环境的坑，我替你踩过了

2.1 必备工具清单

在开始写代码之前，先把下面几样东西准备好。版本号一定要对得上，少走弯路：

注意DevEco Studio一定要装对应你鸿蒙设备API版本的SDK。我一开始装了旧版IDE，配了新版SDK，结果构建日志报了一堆莫名其妙的符号错误，折腾半天才发现是版本错位导致的。

2.2 环境配置要点与小白常见问题

环境变量这一步很多人会忽略。DevEco Studio自带的命令行工具在它内部目录里，不配置全局的话，后面跑构建命令总得去翻IDE安装路径。

我这边配置完后，hdc（HarmonyOS Device Connect，类似adb）是可以全局直接敲的。在终端验证一下：

hdc -v

如果有版本号输出，环境基本就位。没配置的话，把DevEco Studio安装目录下的toolchains路径加到系统PATH里就行。

另一个高频问题是npm镜像源。国内直接下载RN和各种原生依赖经常超时，建议先设置镜像：

npm config set registry https://registry.npmmirror.com

同时鸿蒙SDK的下载建议直接在DevEco Studio的Settings里操作，不要在命令行硬拉，容易断。

注意：Windows机器上如果装了杀毒软件，构建时被拦截文件导致失败的概率不低，关掉实时防护能省很多时间。

3. 创建并打通一个RN鸿蒙工程

3.1 使用社区脚手架初始化工程

目前社区最常用的方案是@react-native-oh/react-native-harmony这条技术路线。它维护了一套完整的RN初版到0.76版本的鸿蒙适配层，安装和初始化都比较成熟。

我用脚手架直接在本地初始化工程，在终端执行：

npx react-native init HarmonyTextDemo --version 0.72.5

初始化完成后，进入项目目录安装鸿蒙适配依赖：

cd HarmonyTextDemo npm install react-native-harmony

这个react-native-harmony包的核心作用，是把RN框架内部的渲染请求转换成鸿蒙ArkUI的组件调用。从某种意义上说，它就像一座桥，让JS侧的Text、View、Image这些组件最终落到鸿蒙原生组件上。

接着，需要用DevEco Studio打开项目里的harmony目录（有些版本脚手架生成的是harmony，有些是harmonyos），让IDE自动识别鸿蒙工程结构。

3.2 已有RN项目适配鸿蒙

如果你手里已经有一个跑得好好的RN项目，想把鸿蒙加进来，操作稍微多一些，但核心就三步：

1. 添加react-native-harmony依赖并安装。
2. 在项目根目录生成鸿蒙工程壳，命令通常是npx rnoh --init，把鸿蒙原生工程包装到你的RN工程里。
3. 在鸿蒙工程里配置RN包的加载入口，包括Metro的bundle地址或本地bundle文件路径。

这里有个经验要点：如果你的RN版本是0.73以上，适配层的API会有差异，一定要先查一下当前版本的官方适配文档，不要想当然地直接按0.72的步骤操作。

3.3 第一个Hello World跑起来

工程配置完成后，先用最简单的方式验证链路。在App.tsx里写一个最小页面，不要加任何复杂库，就一个Text：

import React from 'react'; import { Text, View } from 'react-native'; const App = () => { return ( <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}> <Text>Hello HarmonyOS</Text> </View> ); }; export default App;

然后用DevEco Studio构建并安装到真机。这一步如果白屏，优先查看Log里有没有bundle加载失败的报错。我遇到的首次白屏就是因为Metro服务没有启动，真机拿不到JS代码。解决办法很朴素：先把npm start跑起来，再重新加载应用，基本就好了。

4. 多种文本装饰的实现与差异

前面那些工程层面的东西搞定之后，现在真正进入标题的重点：文本装饰。

所谓“文本装饰”，就是让一段文字不那么朴素的全部手段：加粗、斜体、下划线、删除线、改变颜色、加阴影、加背景高亮、调整字距行距……在React Native中，绝大多数样式属性在Android、iOS、鸿蒙上是可以共用一致的，但也有一部分细节存在平台差异，我会把鸿蒙端的表现单独说明。

4.1 基础文本样式的鸿蒙差异

先看最基础的几个属性：字号、字体粗细、斜体、文本颜色、对齐方式。直接在Text组件的style里写就行：

<Text style={{ fontSize: 24, fontWeight: '700', fontStyle: 'italic', color: '#FF6B6B', textAlign: 'center' }}> 这是一段加粗斜体的大字 </Text>

这里需要特别提一下fontWeight的鸿蒙表现。在Android上，'bold'和数字'700'都能正常渲染；在鸿蒙上，数字形式的字重有时候会被系统忽略，直接落到默认字重上。我的经验是，如果发现加粗没生效，优先检查系统字体对字重的支持情况，或者改用更明确的fontWeight: 'bold'字符串写法。

4.2 下划线、删除线与线型控制

文本装饰线是这个话题的核心，对应的属性是textDecorationLine和textDecorationStyle。用法很直白：

<Text style={{ textDecorationLine: 'underline', textDecorationStyle: 'solid', textDecorationColor: '#2E86AB' }}> 这条下划线是蓝色的实线 </Text>

textDecorationLine可选值包括：

• none：无装饰
• underline：下划线
• line-through：删除线
• underline line-through：同时显示下划线和删除线

textDecorationStyle控制线型，有solid、double、dotted、dashed四种。在鸿蒙上，double的效果跟其他平台可能有细微差异，实测下来solid和dashed最稳定，dotted在某些系统版本上会显示成虚线而非点线。

提示：给文字设置下划线时，我建议同时设置一个略淡于文字颜色的textDecorationColor，视觉层次会更好。纯黑纯白的大色块线在实际界面上很楞。

4.3 阴影、发光与背景高亮

阴影是让文字从背景里“浮”出来的利器。React Native里处理文字阴影有三个属性配合使用：

<Text style={{ fontSize: 32, color: '#FFFFFF', textShadowColor: 'rgba(0, 0, 0, 0.6)', textShadowOffset: { width: 2, height: 2 }, textShadowRadius: 6 }}> 带阴影的白字 </Text>

在鸿蒙端，textShadowOffset同时控制方向和偏移距离，textShadowRadius控制阴影的模糊范围。实测下来，偏移量用2~3，模糊半径用4~8，效果介于利落和柔和之间，够日常使用。

另一种文字装饰思路是背景高亮，类似荧光笔效果。实现起来很粗暴：直接用backgroundColor。

<Text style={{ fontSize: 18, backgroundColor: '#FFF3B0', paddingHorizontal: 4, borderRadius: 2 }}> 这行字自带荧光笔效果 </Text>

这里要留意，paddingHorizontal和borderRadius配合能让高亮区域更紧凑圆润。鸿蒙和Android在这个属性上没有明显差异，放心用。

如果希望只高亮一段文字中的某几个字，就需要嵌套Text组件来实现了。这在我的日常开发里非常常见，比如搜索结果中命中关键词的高亮，做法如下：

<Text style={{ fontSize: 16 }}> 搜索内容中的 <Text style={{ backgroundColor: '#FFD54F', color: '#333', fontWeight: 'bold' }}> 关键词 </Text> 通常需要用高亮突出 </Text>

嵌套Text在很多教程里容易被忽略，但它其实是富文本里最灵活的工具。鸿蒙上对于嵌套Text的支持已经比较完善，背景色、字体色、内边距都能正确继承和覆盖。

4.4 字符间距、行高与大小写转换

这三个属性对文本阅读体验影响很大：

• letterSpacing：字符间距，适合标题或按钮文字，增加辨识度。
• lineHeight：行高，直接影响多行文本的可读性。
• textTransform：大小写转换，uppercase、lowercase、capitalize。

<Text style={{ fontSize: 16, lineHeight: 28, letterSpacing: 0.5, textTransform: 'capitalize' }}> harmony cross-platform text demo </Text>

鸿蒙上lineHeight的坑比较隐蔽：如果字号设置得过大，而lineHeight没有跟着放大，文字会在行内被裁剪。尤其中文场景，显示正常但顶部或底部总有半个笔画消失，非常容易被忽视。我的经验是：lineHeight设置为fontSize的1.5~2倍，多行文本最稳妥。

textTransform在鸿蒙上对拉丁字母生效，对中文没有影响，因为中文没有大小写概念。但如果文本里混了英文单词，这个属性也能一并处理。

4.5 嵌套Text与富文本交互

嵌套Text除了做背景高亮，还能做出更复杂的富文本效果，例如在同一段文字里混合不同的颜色、字号、点击行为：

<Text style={{ fontSize: 15, lineHeight: 22 }}> 我同意 <Text style={{ color: '#1E88E5', textDecorationLine: 'underline' }} onPress={() => console.log('点了用户协议')} > 《用户协议》 </Text> 和 <Text style={{ color: '#1E88E5', textDecorationLine: 'underline' }} onPress={() => console.log('点了隐私政策')} > 《隐私政策》 </Text> </Text>

这种写法在鸿蒙上可以直接响应点击，不需要额外加Touchable组件包裹，整体事件链路是通的。我在真机上实测过，点按命中区域准确，事件回调也正常。

富文本里的一个进阶玩法是给嵌套Text加onLongPress做长按效果，例如长按显示复制菜单。不过鸿蒙上的系统文本选择菜单跟Android不完全一致，如果后续要做类似功能，得针对鸿蒙做一层平台定制。

4.6 自定义字体：鸿蒙端容易忽视的坑

跨平台开发绕不开自定义字体。毕竟系统默认字体各有各的气质，想让应用整体有品牌感，一般都要加载自定义字体文件。

React Native里加载自定义字体的常规做法，是把字体文件放在assets/fonts目录，然后创建一个react-native.config.js文件声明字体资源。但在鸿蒙工程中，光这么做还不行，还得在鸿蒙原生侧把字体文件手动放进resources/base/media或resources/rawfile目录，再在代码里引用。

具体到鸿蒙的逻辑是：RN层设置的fontFamily最终映射到系统中存在的字体名称。如果鸿蒙系统里没有你指定的字体，它会静默降级到默认字体，而且不会有任何报错或警告。我遇到过字体明明没生效但在Android上很正常的情况，排查半天发现就是因为鸿蒙工程里没加字体资源。

所以记住这条：在鸿蒙上加载自定义字体，JS侧和鸿蒙原生侧的资源都要到位，缺一不可。字体文件名最好用英文且不带特殊符号，避免解析问题。

4.7 文本溢出控制的实用方案

文本装饰不只是好看，还要“规矩”。UI开发里最常见的需求之一，是限制文本最大行数，超出后用省略号结尾：

<Text numberOfLines={2} ellipsizeMode="tail" style={{ fontSize: 16, lineHeight: 24 }} > 这是一段很长的描述文本，我们只希望展示前两行，超出两行的部分用省略号代替，剩下部分不显示。 </Text>

numberOfLines控制最大行数，ellipsizeMode控制省略号位置，可选head、middle、tail。在鸿蒙上，tail最常用，也最稳定。

另外还有adjustsFontSizeToFit属性，它允许文本在容器宽度不足时自动缩字号，类似Android的autoSizeTextType。鸿蒙上的支持表现还可以，但要注意它只对单行文本有意义，配合numberOfLines={1}用效果最好。

5. 白屏问题与真机调试速查

5.1 白屏、字体渲染、中文乱码三大高频问题

鸿蒙上跑RN，最常见的三个问题，我在前期全部遇到。整理成一张速查表，方便你对症下药：

白屏问题想高效排查，我强烈建议先用DevEco Studio跑鸿蒙原生日志，过滤ReactNative或JS关键词，多数JS侧的错误都会直接印在Log中。不要闷头在设备上反复重开应用，先看日志再动手。

5.2 真机调试与打包

在真机上调试RN鸿蒙应用，跟Android的无线调试思路类似，但用的工具是hdc。先连接上设备：

hdc list targets

如果看不到设备，检查USB调试是否开启。连接成功后，可以直接用DevEco Studio的Run按钮构建并安装应用，构建速度比Android工程慢一点，但属于正常感受范围。

日常开发中，如果只想改UI样式而不动原生代码，完全不用反复构建hap包。启动Metro后，鸿蒙应用可以从DevEco Studio一键加载本地bundle，改动JS代码后刷新页面即可，整个体验跟RN常规开发一致。

等代码稳定需要真机验证性能，再执行构建生成hap包安装，打包命令可以用DevEco Studio的Build菜单里的Build Hap(s)/APP(s)，也可以在命令行执行hvigorw assembleHap。

5.3 我的事故清单

踩过的坑里挑三个影响最大的写在这里，希望你能绕开：

1. 版本强绑定：react-native-harmony适配层的版本跟RN版本是强绑定的。不要随便升级RN版本而忘记同步检查适配层，否则会在构建时遇到各种诡异错误。

2. 中文文件名资源：我把一个字体文件命名成“思源黑体-粗.otf”，在Android上一切正常，到鸿蒙构建时直接报资源错误。后来改名为英文字体名，重新构建才通过。鸿蒙工具链对非ASCII资源名的兼容性有待提升，避开最稳。

3. 模拟器与真机差异：模拟器上表现良好的动画和渲染效果，到了真机上有时会掉帧，尤其是文字阴影面积很大的场景。做性能验收时务必用真机跑一遍，别只依赖模拟器。

6. 从文本装饰延伸出的几条实操经验

6.1 动画和触摸反馈能让装饰真正“活”起来

文本装饰做完了，静态界面的品质感基本到位。但如果想让交互体验上一个台阶，可以给文本加上简单的动画反馈。RN自带Animated库，在鸿蒙上同样可用。

比如给按钮文字加一个点击时稍微变色的效果：

const opacity = useRef(new Animated.Value(1)).current; const handlePressIn = () => { Animated.timing(opacity, { toValue: 0.6, duration: 100, useNativeDriver: true }).start(); }; const handlePressOut = () => { Animated.timing(opacity, { toValue: 1, duration: 150, useNativeDriver: true }).start(); }; <Animated.Text onPressIn={handlePressIn} onPressOut={handlePressOut} style={{ fontSize: 16, opacity, color: '#333' }} > 点我会有反馈 </Animated.Text>

关于useNativeDriver，在鸿蒙上把它设为true在大部分情况下能驱动透明度、位移这类属性。如果碰到动画没有执行，先尝试把useNativeDriver改成false再用原生驱动排查。

6.2 性能小讲究：别让文本装饰拖垮页面

文本装饰看着轻巧，但在列表页面大量渲染时会积累性能压力。三个实用原则：

• 固定numberOfLines：列表里的长文本如果不限制行数，每个Item高度都可能不同，不仅视觉杂乱，还会导致布局计算量放大。
• 少用大面积textShadow：阴影模糊计算开销不小，尤其在长列表滚动场景，全屏文字的阴影会导致掉帧。装饰只用在标题和关键文字上。
• 不要过度嵌套Text：虽然嵌套Text很灵活，但嵌套层级过深会增加渲染树的计算量。能用单个Text和拼接解决的，就不要套三层。

6.3 从文本到整个跨平台生态

把多种文本装饰摸透之后，你其实已经掌握了React Native在鸿蒙上工作的核心链路：从组件属性到样式映射，从真机调试到日志排查。这条路再往下延伸就是ScrollView、FlatList、Image、网络请求、状态管理等更多话题。

我做这个项目时的体会是：文本装饰虽然小，但对理解“RN代码如何在鸿蒙上变成真实UI”非常有帮助。毕竟UI的本质就是一堆文本、图片和布局的排列组合，能在文本这条线上跑通整个开发闭环，后面的模块大多是水到渠成。

最后分享一个小技巧：在你第一次在鸿蒙真机上渲染出自定义样式文本的那一刻，先别急着做更多功能，多尝试几个字体、几组颜色、几种阴影组合，用截图记录一下鸿蒙上每个样式属性的真实表现。这套“鸿蒙平台样式基准库”在后续项目里会被频繁用到，能替你节约大量跟设计对细节的时间。