前阵子在做公司内部的鸿蒙化改造,把现有的React Native业务代码往OpenHarmony生态上迁移。迁移本身其实还好,真正折腾人的是业务里的那些复合组件——尤其是订单流程里到处都要用的步骤条。这东西看着简单,不就是几个圆点和几条横线嘛,可真要做得能对齐、能自适应、能在不同屏幕和字体缩放下不炸,再叠加鸿蒙那边的平台差异,就完全不是一回事了。
我这一篇是“React Native鸿蒙跨平台开发高级复合组件库开发系列”里的实操记录,拿订单步骤条当例子,把从设计思路、API规划、核心实现到鸿蒙适配踩坑的完整过程捋一遍。内容会涉及RNOH(React Native for OpenHarmony)的适配差异、状态机设计、 HAR打包发布、以及我在白屏和布局错乱上排到吐血的真实经历。如果你正在给团队搭RN组件库,或者马上要把现有RN工程搬到鸿蒙设备上跑,这篇应该能帮你少走不少弯路。
1. 项目定位与设计思路
1.1 为什么要在RN鸿蒙环境里自研复合组件
先聊个基础问题:ArkUI里明明有Step组件,为什么还要在RN侧自研一个步骤条?
答案是:跨端一致性。
一个成熟的跨端组件库,应该保证iOS、Android、HarmonyOS三端渲染出来的视觉效果和交互行为完全统一。如果我们直接在各端用原生组件拼,那等于每个端维护一套实现,视觉走查的时候逐端对,开发成本直接翻倍。而RN侧的优点就在于,业务代码只需要写一份,通过react-native-harmony这套适配层,把JS组件映射到鸿蒙的ArkUI组件上。
我自己实际跑下来,RNOH目前已经能覆盖绝大多数基础组件(View、Text、ScrollView、Pressable这些都没问题),但对于步骤条这种复合组件,RN侧完全可以从零绘制每个节点、连线和状态,不依赖任何端上独有的原生组件。这样做的好处有两个:
- 视觉统一,因为所有节点都是我们用View+Text+Animated拼出来的,三端渲染出的像素级基本一致。
- 可定制性强,业务方传什么颜色、尺寸、图标,组件内部自己消化,不牵扯原生逻辑。
1.2 订单步骤条的功能拆解
先看看订单步骤条在真实业务里要承担哪些职责:
- 展示订单当前所处阶段,比如“待付款 → 已付款 → 已发货 → 已签收”。
- 当前步骤要突出显示,已完成步骤要有明显的“已完成”视觉反馈,未完成步骤要弱化。
- 支持用户点击步骤节点切换查看对应阶段详情(如果业务需要的话)。
- 支持横向排布(一行展示)和纵向排布(左侧时间轴样式)。
- 步骤数量不固定,可能3步,也可能8步,要能自适应宽度。
- 可能出现失败状态,比如“支付失败”,节点需要展示异常样式。
这些需求放在一个组件里,就需要我们抽象一套清晰的数据模型和状态机。一开始我脑子里的设计很朴素,直接用一个current字段加两个颜色变量,结果真写到第六步的时候发现逻辑根本理不清。后来我参照Redux处理状态的方式,给步骤节点的状态做了枚举,整体代码瞬间清爽了。
1.3 组件库的分层策略
既然目标是“组件库”,就不能只做一个孤零零的步骤条。我在这套代码里同时埋了分层设计:
- 展示层(View Layer):只负责根据数据渲染UI,不关心数据从哪来。
- 逻辑层(Logic Layer):处理步骤状态流转、点击回调、受控模式等。
- 适配层(Adapter Layer):针对RNOH差异做兼容,比如字体缩放、安全区、自定义组件注册等。
这样做的好处是,以后如果要接Taro、要接纯ArkUI,只需要换掉适配层,核心状态逻辑可以直接复用。对于团队来说,这种设计投入的边际成本很低,但长期维护价值很高。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 组件API与数据模型设计
2.1 定义步骤条的数据模型
代码写得好不好,一半看数据模型定义得好不好。这个组件的核心数据结构是这样的:
typescript复制export type StepStatus = 'wait' | 'process' | 'finish' | 'error';
export interface StepItem {
title: string;
description?: string;
status?: StepStatus;
icon?: React.ReactNode;
disabled?: boolean;
extra?: React.ReactNode;
}
export interface StepsProps {
items: StepItem[];
current?: number;
status?: 'process' | 'error';
direction?: 'horizontal' | 'vertical';
onChange?: (index: number) => void;
finishIcon?: React.ReactNode;
processIcon?: React.ReactNode;
errorIcon?:
