React Native鸿蒙化：评分组件重写与启动白屏排查实践

做 React Native 鸿蒙化这几个月，我踩得最痛的不是什么复杂页面，反而是一个平时根本不起眼的评分组件。老项目里一直用的是第三方评分库，在 iOS 和 Android 上跑得挺好，结果换到 React Native for Harmony 这套环境上，直接白屏、点不动、星星显示成方框，所有问题一股脑全冒出来。后来我把这个 Rating 组件重写了一遍，支持全星、半星、禁用、自定义样式，同时在鸿蒙真机和模拟器上验证通过。

这篇文章就把我的实现思路、代码细节、踩坑过程，以及大家最常遇到的“react native 启动白屏”问题怎么排查，完整分享出来。如果你也在做 React Native 鸿蒙适配，或者正准备在 HarmonyOS 里做一个评分类组件，可以少走不少弯路。

1. 为什么是“鸿蒙定制”的 Rating，而不是直接用第三方库

1.1 我迁移过程中遇到的三类问题

先说背景。我的项目是基于 React Native 0.72.5 做的，需要用 react-native-harmony 这套鸿蒙适配方案把它跑到 HarmonyOS 设备上。一开始我天真的想法是：Rating 这种组件又不复杂，原样搬过去就能用。

现实很快打脸。第一类问题是第三方库本身没有鸿蒙适配。很多从 npm 安装的评分组件内部用了 iOS 和 Android 的专属组件，比如SafeAreaView、TouchableNativeFeedback、Platform.select里大量平台分支，这些在鸿蒙适配层要么没有实现、要么行为不一致。评分库往往还会依赖一些字体图标文件，比如react-native-vector-icons，在鸿蒙环境里字体文件加载路径完全不一样，结果就是星星直接变成方块。

第二类问题是触摸事件差异。评分组件核心是一颗颗可点击的星星，最常见的事件模型是TouchableOpacity包一层，然后在onPress里取值。Android 和 iOS 上这套逻辑毫无问题，但在鸿蒙的 RN 兼容层上，我遇到的实际情况是：动画不够跟手、点击区域偶尔丢失、连续快速点击评分会出现漏事件。后来我才意识到，这不是组件写得不对，而是对触摸事件处理的方式需要更“底层”一点。

第三类问题是半星的视觉实现。第三方库实现半星，大多用两张星星图片叠起来，一张灰色的底，一张亮色的顶，顶图宽度按百分比裁切。听起来很简单，但在鸿蒙上，图片裁切用overflow: 'hidden'是有效的，可如果星星不是图片而是字体图标，裁切对齐就会出现像素级误差。半星本来就是视觉细节要求很高的东西，一旦对齐不准，用户一眼就能看出来。

这些问题单个拆开都不致命，叠在一起就足够让人崩溃。所以最靠谱的方案，就是自己维护一个专用于 React Native for Harmony 的 Rating 组件。

1.2 自研与原生封装的取舍

在动手之前其实还有个选择：直接用 ArkUI 自带的Rating组件做底层封装，通过原生桥接暴露给 RN 调用。

这个方案的好处是性能好、原生交互自然，坏处也明显：需要写 ArkTS 原生代码、注册组件、管理桥接，对纯 JS/TS 团队来说维护成本不低。尤其像评分这种轻交互组件，性能敏感度其实没那么高，一点响应时间差异用户根本感知不到。

所以我最后选择了纯 JS/TS 方案：不依赖任何第三方 UI 库，只在 RN 基础组件之上自绘星星逻辑。这样做的收益很直接：代码可以在 iOS、Android、Harmony 三端百分之百复用；不绑定特定的字体包；样式自由度极高，想改颜色、尺寸、图标、背景都非常容易；排查问题也简单，因为整条链路都在自己手里。

代价是：需要自己处理触摸手势、状态管理和视觉细节。但这恰恰是我写这篇文章想要填平的坑。

2. Rating 组件整体设计与 API 定义

2.1 对外 API 与 Props 设计

一个评分组件的 API 设计，直接决定它好不好用。我参照了社区里几款主流评分库的用法，同时结合鸿蒙场景做了一些调整。下面是我最终定下来的 Props 设计：

受控还是非受控，我倾向于跟 Input 组件一样做“半受控”：父组件传value进来展示状态，用户点击时通过onPress通知父组件修改。组件内部默认不做 setValue，这样评分状态始终掌握在业务层手里，跟表单校验、提交逻辑配合起来最舒服。

maxStars不建议定死为 5，因为实际业务里经常有 3 星（食堂服务评分）、7 星（某些平台精评分）的需求，做成参数一劳永逸。

关于间距，我加了一个spacing而不是用gap，原因是鸿蒙适配层对gap的支持在特定 RN 版本里会有兼容问题。用显式marginRight虽然冗余一点，但兼容性最好。

2.2 组件分层结构

实现上我分成了两个文件：Rating.tsx负责整体交互逻辑，Star.tsx负责单颗星的渲染。分层的理由很简单：评分组件的交互难点在“如何定位到星星”，视觉难点在“如何画出一颗半星”，两者拆开之后，改交互不影响视图，改视图不需要动交互。

组件结构大致是这样：

Rating ├── 外层容器 View │ ├── Star（第 1 颗） │ ├── Star（第 2 颗） │ └── ...

外层容器需要设置flexDirection: 'row'，同时处理触摸事件。Star 组件只接收一个fill参数，表示这颗星的填充比例，0 代表全灰，1 代表全亮，0.5 就是半亮。

我最初尝试过把整个评分条画在一个 Canvas 里，通过绝对坐标算星星位置，但那样做在鸿蒙上非常容易踩到像素密度换算的坑。用单颗 Star 独立组件、各自循环渲染的方式，虽然组件数量多一点，但每个组件边界清晰，定位计算也简单到几乎不可能出错。

3. 核心功能实现：全星、半星、禁用与自定义样式

3.1 全星与点击评分

先说最基础的场景：5 颗星，点击第 3 颗，评分就是 3。

实现时我用了响应系统（Responder System）而不是简单地给每颗星包TouchableOpacity。原因开头提过，TouchableOpacity在鸿蒙适配层下偶尔会出现点击丢失或动画卡顿，而响应系统是 RN 触摸事件的最底层机制，兼容性最稳。

核心代码是这样的：

// Rating.tsx 核心逻辑 const handleStartShouldSetResponder = () => true; const handleResponderRelease = (event: GestureResponderEvent) => { if (disabled) return; const { locationX } = event.nativeEvent; const starUnit = size + spacing; // 计算落在第几颗星 const nearbyStar = Math.floor(locationX / starUnit) + 1; // 限制边界 const value = Math.min(Math.max(nearbyStar, 1), maxStars); onPress?.(value); };

这里有个关键细节：locationX是相对于响应者容器的坐标，所以拿到之后要先除以(size + spacing)，算出是第几颗星。Math.floor拿到的是索引，加 1 才能对应到“第几颗”。

整颗星渲染很简单，用文字符号或图片都行。我的默认实现用fontSize: size的 Text 加 Unicode 星形字符：

// Star.tsx 全星渲染 const Star = ({ size, color, text }) => ( <Text style={{ fontSize: size, lineHeight: size, color, textAlign: 'center', }}> {text} </Text> );

有人会问，用字符做星星会不会在鸿蒙上显示不出来？确实有可能，这取决于设备字体文件。所以我在customRender上留了口子，业务方可以直接传自己的图片或自定义字体组件。后面会细讲。

3.2 半星是怎么做出来的

半星是整个组件里视觉最微妙的部分。我的方案是：一颗星拆成两层。

第一层是底层，完整渲染一个灰星；第二层是顶层，渲染一个亮星，但外层包一个宽度为size * fill的裁切容器，overflow: 'hidden'，这样亮星只露出左侧一部分，看起来就是半亮。

代码大概是这样：

// Star.tsx 半星实现 const Star = ({ size, fill, color, activeColor, starText }) => { const baseText = starText ?? '★'; return ( <View style={{ width: size, height: size }}> {/* 底层灰星 */} <Text style={{ fontSize: size, lineHeight: size, color }}> {baseText} </Text> {/* 顶层亮星，宽度按 fill 比例裁切 */} <View style={[ StyleSheet.absoluteFill, { width: size * fill, overflow: 'hidden' }, ]}> <Text style={{ fontSize: size, lineHeight: size, color: activeColor }}> {baseText} </Text> </View> </View> ); };

这里需要特别注意两点。

第一，StyleSheet.absoluteFill在鸿蒙 RN 上一定要放在顶层裁切容器上，这样两层的文字才可能完全对齐。如果直接写position: 'absolute', top: 0, left: 0，效果一样，但absoluteFill更简洁。

第二，裁切容器必须显式设置width: size * fill，不能只依赖内部 Text 撑开。因为overflow: 'hidden'的生效前提是容器自身有确定尺寸，否则在部分鸿蒙机型上会出现裁切失效，亮星直接整颗显示。

点击交互上，半星模式的定位要细化到“半颗”。我改用手势locationX，先算出是第几颗星，再算手指在这一颗星内部的横向偏移：

const handleResponderRelease = (event: GestureResponderEvent) => { if (disabled) return; const { locationX } = event.nativeEvent; const starUnit = size + spacing; const index = Math.floor(locationX / starUnit); const offset = locationX - index * starUnit; // 点击落在左半边还是右半边 const isLeft = offset < size / 2; let value = index; if (allowHalf && isLeft) { value = index + 0.5; } else { value = index + 1; } onPress?.(Math.min(Math.max(value, 0), maxStars)); };

用户点第 2 颗星的左半边，得到 1.5，点右半边，得到 2。符合直觉。

3.3 禁用状态与无障碍处理

禁用状态最简单，也最容易做漏。

我给的方案是三层防护：

const handleResponderGrant = () => { // 第一层：不响应触摸 if (disabled) return; }; // 第二层：容器视觉降级 <View style={[ styles.container, disabled && styles.disabled, style, ]}>

第三层是在业务侧：就算组件内部都判断了，父组件依然不应该收到onPress。这个由上面的if (disabled) return;保证。

视觉表现上，禁用分两种：完全置灰，或者维持评分成色不变但降低透明度。我默认采用降低透明度，因为有些业务需要在禁用态仍然展示当前评分，比如订单完成后的“本次服务评分 4.5 星”，颜色如果全灰了，用户的阅读成本会上升。

无障碍方面我个人推荐不要省掉accessible和accessibilityLabel。虽然很多 RN 鸿蒙项目暂时不会专门做无障碍测试，但评分这类信息对屏幕阅读器用户很重要。我建议在容器上加一个动态的accessibilityLabel：评分，当前值四点五星，共五颗星。这样至少基础语义是通的。

3.4 自定义样式的完整玩法

自定义样式这块，我把它拆成三个层次，覆盖不同复杂度需求。

第一层是少量调整，通过Props改颜色和尺寸。color、activeColor、size三个参数覆盖 80% 的场景。比如商家好评率展示用金色，课程评价用蓝色，短视频 App 用粉色，改一行 props 就够。

第二层是替换星星形状。starText可以改成'★'、'☆'、'\u2605'，也可以用网络图片或本地图片。图片模式的实现是把 Star 内部的 Text 换成 Image：

const StarImage = ({ size, fill, source }) => ( <View style={{ width: size, height: size, overflow: 'hidden' }}> <Image source={source} style={{ width: size, height: size, opacity: fill >= 1 ? 1 : 0.4, }} /> </View> );

图片模式下如果想做半星，就不能用这一节前面提到的遮罩文字方案了。我的做法是直接用两张图叠加，底层灰图完整展示，顶层亮图用一个width: size * fill的裁切容器包住。这样不管星星是字体还是图片，半星逻辑都能复用同一套fill参数。

第三层是完全自定义渲染节点。我在 Rating 里加了customRender，它接收当前星星的索引和激活状态，返回任意 ReactNode。比如有些 App 的评分图标是个大拇指，或者是个厨师的卡通头像，这种需求必然靠这个口子解决。

我在实际项目中就接过一个需求：星级用表情符号比较难统一，业务方最后用了 5 张不同的图标，分别对应“非常差”到“非常好”，每颗星星不仅颜色不同、形状也不同。这种需求只有customRender能干净地承接。

4. 在 React Native for Harmony 工程里跑起来

4.1 组件引入与最小接入

组件本身写完后，接下来就是把它接进 React Native for Harmony 工程。这一步看起来简单，实际上很多人的项目连这一关都过不去，因为环境配置细节容易踩坑。

我以自己用的 0.72.5 版本为例说流程。首先确认项目已经初始化好 harmony 目录：

npx react-native init RNHarmonyRatingDemo cd RNHarmonyRatingDemo npm install react-native-harmony npx react-native-harmony init

初始化完成后，用 DevEco Studio 打开工程里的harmony目录。需要注意，React Native 版本和 react-native-harmony 版本不是随便配的。比如 0.72 系列的 RN 要搭配对应 0.72.x 的 react-native-harmony，不能直接拿 0.73 或 0.74 的适配包硬上。具体版本对应关系去仓库的 Release 页面对一下就行。

接入 Rating 组件就很简单了。把Rating.tsx和Star.tsx放进项目的src/components/Rating目录，然后在业务页面里：

import Rating from './src/components/Rating'; <Rating value={score} maxStars={5} allowHalf activeColor="#ff9500" onPress={(value) => setScore(value)} />

如果项目是纯 TypeScript，强烈建议顺便导出一份RatingProps类型。我用这个组件的时候，父组件的状态类型用的是number而不是string，看起来是小事，但表单提交时1.5变成"1.5"再转回数字的啰嗦事真的太多了。

4.2 启动白屏的排查与解决

热搜里“react native 启动白屏”我没有具体出处，但 React Native for Harmony 项目启动白屏几乎每个人都会遇到，我自己也在接入评分组件时被这个问题卡了整整一个晚上。

白屏的本质是：应用起来了，但 React Native 的 JS Bundle 没有正确加载。在鸿蒙上最常见的原因有这几个。

第一个原因：Metro 服务没有启动，或者设备的 Metro 地址不通。开发模式下，React Native 需要一个 dev server 提供 bundle。鸿蒙真机要和电脑处于同一局域网，并且需要在 DevEco 里配置正确的 server host。可以在启动时通过 Metro 终端观察有没有设备来拉取 bundle：

npx react-native start

如果终端里一直没有出现“Building/HMR”之类的日志，基本就是设备还没连上 Metro。此时优先检查网络和端口。

第二个原因：release 包没有打 bundle。如果直接跑 release 模式，但没有提前执行 bundle 命令，应用启动后找不到 JS 文件，就会白屏。对应到鸿蒙工程，需要在 harmony 目录里确认是否有打包好的 bundle 资源，并且在EntryAbility里配置正确的 bundle 路径。

第三个原因：权限缺失。鸿蒙应用访问本地 Metro 服务需要一个很基础的网络权限，必须在entry/src/main/module.json5里声明：

{ "name": "ohos.permission.INTERNET" }

没有这个权限，release 包加载本地 bundle 还好，debug 包走网络加载必然失败。

第四个原因相对隐蔽：EntryAbility的窗口时序。React Native 的容器需要等窗口创建完成后再加载 JS，有些工程模板默认的加载时序在部分 API 版本的 SDK 上会出问题，表现为窗口已显示但 JS 迟迟不渲染。我当时的排查方式是打开 DevEco 的日志，看到类似loadBundle failed的报错，才定位到时序问题。

分享一个我常用的白屏排查顺序：[是否 dev 模式] → [Metro 日志有没有请求记录] → [module.json5 网络权限] → [bundle 是否已生成] → [EntryAbility 时序]。按这个顺序找，基本五分钟内能定位到问题。

5. 踩坑实录与问题速查

5.1 高频坑

我整理了几个评分组件在鸿蒙适配中高频出现的坑，做成速查表，方便你直接对照。

第 4 个坑我专门说一句。做半星触摸定位时，很多人只算了size，忘了星星之间还有spacing。结果就是点第 3 颗星的右半边，系统以为是第 4 颗星的左半边，评分直接偏移半颗星。横竖都对不上，特别烦人。后来我在代码里统一用一个变量starUnit = size + spacing，所有定位计算都基于它，这个问题就再没出现过。

第 5 个坑也值得展开。评分组件本身很小，但如果父组件每次都创建新的数组或函数传入，Rating 内部所有 Star 都会重新渲染。业务页面如果比较重，评分时会明显感觉卡顿。我的解决方式是给每个 Star 包一层React.memo，并且确保onPress通过useCallback传递。

const handleRatingPress = useCallback((value: number) => { setScore(value); }, []);

这里有个残次品：如果你传了customRender，那就没法做标准化 memo，因为自定义函数每次父组件渲染都会变化。建议业务层用useMemo包一层customRender，同时 Star 的 memo 比较逻辑里把这个函数引用考虑进去。

5.2 排查工具与方法

最后分享几个我实测有效的调试方法。

第一个方法是给 Rating 组件加一个临时的可视化调试开关。我在开发版里会导出一个debug属性，开启后会在星星周围画一圈虚线边框，并且在视觉层打印locationX的实时数值。定位触摸偏移问题时，这个开关比任何日志都直观。

第二个方法是利用 Metro 的日志。鸿蒙设备连接 Metro 后，按r可以 reload，按d打开 dev menu。遇到白屏问题时，别急着改代码，先把 Metro 日志窗口最大化，看看请求状态。

第三个方法是善用日志分级。不要一上来就console.log满天飞，把需要排查的点位拆清楚：容器布局、Touch 事件、Star 渲染、父组件回调，各自打不同的前缀。我习惯用[Rating][layout]、[Rating][touch]这种标签格式，搜索日志时非常高效。

我目前这个评分组件已经稳定运行在商详页、订单评价页和直播评分弹窗三个场景里，全星、半星、禁用、自定义表情图标、简体中文与英文双语显示都验证过。如果要做后续扩展，还有两个方向我觉得值得接下去做：一个是滑动评分，手指在星星上横向滑动连续打分，体验会更顺滑，但需要把handleResponderMove加进去，计算位置时要额外处理快速滑动时的消息抽样；另一个是评分后触发打点或轻提示动画，让用户的评分行为获得即时正向反馈。这个组件本身结构很轻，这两个方向都在原思路上做增量，不需要推翻重来。