业务侧的产品经理把需求文档递过来时我确实没太当回事——折叠面板做个能展开收起的列表呗。真正动手之后才发现在 React Native 鸿蒙化Harmony这套体系里一个看着不起眼的 Accordion 组件能把测量、动画、启动渲染、资源加载的坑全踩一遍。当时团队正在推进企业级跨端组件库建设折叠面板是首批被点名要做的组件之一要求还挺严切换要顺滑、要支持深色模式、要过无障碍检测、还得在低端鸿蒙机器上不卡顿。我去社区翻了一圈现成方案结果越翻越心虚——主流折叠面板组件在鸿蒙适配版本上的表现大多不靠谱有的依赖的手势库在鸿蒙运行时上支持不全有的动画实现直接踩了非原生驱动属性的坑还有的连 TypeScript 类型定义都残缺不全。最后结论只有一条自己动手老老实实基于 RN 鸿蒙运行时写一个企业内部通用的折叠面板组件。这篇文章就是这段完整过程的记录包括需求拆解、方案取舍、高度动画的实现细节以及顺带揪出来的“react native 启动白屏”问题适合正在为鸿蒙平台做 RN 组件选型、或者被首屏白屏问题折腾得焦头烂额的同路人参考。1. 决定自研之前我拿需求清单把现成库挨个否了一遍1.1 企业级折叠面板的需求清单不是“能展开收起”这么简单很多人在做折叠面板时第一反应是找社区库然后发现 demo 跑得挺顺一接入真实业务就崩。原因很简单企业级组件和 demo 组件的验收标准根本不是一个维度。我列了一下当时业务侧提过来的需求大概有这么几条支持受控/非受控两种用法且展开状态需要在页面级可管理一屏内多个折叠项需要支持“互斥展开”——也就是经典的 Accordion 语义展开一个自动收起其他动画必须可中断用户在动画播放到一半时再次点击要能从当前状态平滑过渡到新状态不能闪跳内容高度是动态的可能包含图片、长文本、异步加载的数据不能假设固定高度深色模式要跟随系统切换无障碍要求屏幕阅读器能读出当前“展开/收起”状态能用键盘操作低端机上动画不能造成明显掉帧内存占用不能因为收起/展开的次数增长。这七条列出来之后事情就清晰了市面上大多数折叠面板组件做的都是“能跑”这个层面前面的需求至少有三四条它们满足不了。比如动态内容高度这个点很多实现直接用maxHeight做近似内容一长就露馅再比如互斥语义有些库管自己叫 Accordion实际上却是多个独立面板共存逻辑上完全不是一回事。1.2 社区组件在鸿蒙适配前的真实短板我在评估现成方案时特意把 React Native 鸿蒙运行时的适配情况考虑进去。这个前提下社区库的问题暴露得更明显。第一类问题出在依赖上。不少折叠面板组件依赖react-native-gesture-handler和react-native-reanimated。这两个库在 iOS/Android 上是标配但在鸿蒙适配版本上的支持程度是打折扣的。手势库的部分手势事件在鸿蒙运行时上的触发时机和 Android 有明显差异而 Reanimated 的 worklet 机制在鸿蒙上的兼容性也不是百分百这就导致同一个组件在不同平台上的表现完全不可控。让一个组件库的稳定性建立在另一个本身还不稳定的生态依赖上这在企业级项目里是真正的隐患。第二类问题出在实现细节上。有些组件为了做高度动画用maxHeight从 0 过渡到几百视觉效果在内容多的时候非常别扭展开速度还会因为内容实际高度和预设值不一致而忽快忽慢。有些组件把文字大小、背景颜色、圆角写死在样式里深色模式适配基本靠业务侧自己罩一层样式覆盖用起来很痛苦。还有的组件连展开状态都没有暴露到无障碍树里无障碍检测一跑就报警。第三类问题更现实维护状态。开源组件往往是一个人或两三个人在维护RN 版本一升级鸿蒙适配版本一改变这些库可能就处于“能用但没人管”的状态。对一个要做长期演进的企业组件库来说核心基础组件掌握在自己手里比依赖一个随时可能断更的外部库要稳妥得多。1.3 自研的边界不是从零造轮子这里我得说清楚自研不等于闭门造车。我当时的策略是参考社区成熟组件的 API 设计思路但实现层全部基于鸿蒙实际表现重写并且把“可测试、可测量、可降级”作为硬指标。组件的大体结构是分成两层外层是容器组件Accordion负责管理展开项的 ID 列表、互斥策略、受控状态内层是列表项组件Accordion.Item负责单个面板的头部、内容包裹、动画驱动。这样设计的好处是业务侧的用法贴近原生直觉而且内部逻辑可以独立测试后面章节我会把最终 API 完整展示出来。2. 交互模型先于样式定稿受控性、互斥与手势2.1 受控还是非受控企业级组件库的必修课折叠面板这类带内部状态的组件进组件库之前必须先回答一个问题这状态归谁管。非受控用法简单组件内部自己维护展开项业务方只管传内容和标题适合快速接入但碰到“点一个按钮把全部折叠项展开”“从外部跳转让特定面板展开”这类需求非受控就使不上劲了。受控用法把展开项列表交给业务方管理类似useState的循环组件触发变更时通过onChange回调告诉外部外部再把新的展开项列表传回来。我最终的实现是两种模式都支持用的也是社区常见的受控/非受控自动切换思路interface AccordionPropsT { /** 受控模式当前的展开项 ID 列表 */ value?: T[]; /** 非受控模式初始展开项 ID 列表 */ defaultValue?: T[]; /** 展开状态变化时回调changedId 是本次被点击的项 */ onChange?: (value: T[], changedId: T) void; /** 是否允许展开多项默认 false即互斥展开 */ expandMultiple?: boolean; /** 是否开启动画默认 true */ animated?: boolean; }判断标准很简单业务方传了value就走受控分支内部状态只在用户操作时作为中间缓存没传就走非受控分支组件自己存状态。这个设计看起来简单但实际很关键——很多折叠面板组件翻车就是因为只做了非受控业务方想重置状态都找不到入口。2.2 单开互斥还是多开并存语义差一个单词这里我想多说一句命名的事。英文里Accordion和Collapse其实是有微妙区别的Accordion 强调“一次只能展开一项”像手风琴一样一个键按下去另一个键就弹回来Collapse 则允许任意多个面板独立展开。国内很多组件库把这两者混为一谈导致语义混乱。我们组件既然叫 Accordion默认行为就应该是互斥的。所以expandMultiple默认是false。实现互斥逻辑时有一个小细节要处理当用户点击当前已展开的面板时应该把它收起而不是保持展开状态等待其他面板收起。这个“再次点击收起”的行为在 set 操作里表现为 toggle而不是单纯地往列表里添加。const nextExpanded new Set(prevExpanded); if (nextExpanded.has(id)) { nextExpanded.delete(id); } else { if (!expandMultiple) nextExpanded.clear(); nextExpanded.add(id); }这段代码简单但它是整个互斥语义的基石。后面攻克方向时发现业务侧对互斥的理解其实往往是从视觉上来的——如果展开项之间有间距互斥展开按视觉就够清楚但有些业务场景需要保留上一个面板的滚动位置那偏要靠“多开并存”才能实现。所以最终默认互斥但不锁死通过expandMultiple放开。2.3 为什么我暂时没有默认开启滑动展开折叠面板除了点击头部展开之外还有一种交互形式是滑动展开——按住面板内容边缘向上/向下拖高度跟随手指移动。这种交互在移动端知识库、表单类页面很常见也确实更“原生”。但我在这一版里没有默认开启。原因很简单在鸿蒙的 RN 运行时里滑动和ScrollView的手势竞争很微妙。手指在面板头部或者内容区域滑动时到底是应该滚动外层列表还是应该拖动面板本身要实现得丝滑需要引入手势识别优先级和滑动阈值。而当前姿态下强行上手势反而会带来误触、卡顿等不稳定因素企业级场景里稳定性大于交互炫技。我的折中方案是把滑动展开做成“可选增强能力”通过gestureThreshold等参数预留扩展位默认关闭。同时头部点击是基础交互无论什么环境都能正常工作无障碍和测试也都围绕点击主路径展开。这样既照顾了产品理想又守住了工程底线。3. 高度动画才算真正的硬骨头onLayout、Animated 与字体测量的三重坑3.1 为什么 maxHeight 路线注定翻车折叠面板最核心的视觉就是“高度变化”。很多人在这一步图省事直接给内容容器设一个maxHeight然后动画过渡 maxHeight 从 0 到几百。这种做法在内容高度固定、且你提前知道内容大概多高的时候能用但在企业级场景里问题很明显。内容高度是动态的。可能是接口返回的用户协议可能是运营配置的一句话也可能是图片加载完成后撑开的高度。maxHeight设大了动画后半段速度感突变设小了内容被截断或者出现明显空白。为了让动画匀速、精确、可复现必须拿到内容区的真实高度这只能靠onLayout。另外一个最直接的否决原因maxHeight动画在内容具有不同 padding 时会出现一种很丑的“先展开 padding 再展开内容”的滞后感视觉上像是面板在“拖堂”。真实内容高度 单值驱动的方案能避免这个问题。3.2 用 onLayout 量高度用 Animated 驱动我最终的实现方案核心结构是这样的const [contentHeight, setContentHeight] useState(0); const [headerHeight, setHeaderHeight] useState(0); const animHeight useRef(new Animated.Value(headerHeight)).current; const isExpandedRef useRef(false); const measuredHeight contentHeight headerHeight; const toggleTo useCallback((expanded: boolean) { // 先停掉当前动画拿到当前实际高度避免闪跳 animHeight.stopAnimation((current) { const targetHeight expanded ? measuredHeight : headerHeight; animHeight.setValue(current); Animated.timing(animHeight, { toValue: targetHeight, duration: 260, easing: Easing.out(Easing.cubic), useNativeDriver: false, }).start(); }); }, [animHeight, measuredHeight, headerHeight]);内容区结构上做了一个重要设计外层Animated.View控制高度并设置overflow: hidden内层再套一个独立的View接收onLayout。这样做的原因很微妙——如果直接把内容放进被动画控制高度的容器里当外层高度被压缩成headerHeight时内层内容虽然被裁剪了但它自身的布局高度仍然是完整的因此onLayout能拿到真实内容高度。反过来如果把内容高度和外层动画高度合在一个组件里onLayout的返回值会被动画过程污染折叠时拿到 0展开时拿到真实值逻辑很难写。Animated.View style{{ height: animHeight, overflow: hidden }} View collapsable{false} onLayout{(e) { const h e.nativeEvent.layout.height; // 略微容差避免死循环 if (Math.abs(h - contentHeight) 0.5) { setContentHeight(h); } }} {children} /View /Animated.ViewuseNativeDriver: false这个参数必须显式写。原因很多读者应该知道Animated的原生驱动只支持transform和opacity这类可以在原生层直接计算的属性height不在其中在鸿蒙运行时上同样如此。如果这里误设成true动画不会生效控制台会打警告。3.3 三个实测踩到的测量坑这版组件从能跑到能看中间处理了三个测量相关的坑我记录在这里方便后来人直接避开。第一个坑是首次渲染时onLayout的异步性。组件刚挂载时内容是真实的但contentHeight初始是 0导致第一次展开动画的目标高度缺少内容部分画面会“弹”一下。解决方案是在组件挂载后立即读取一次高度并且让展开动作至少在首次onLayout返回之后才能触发或者在受控场景下用InteractionManager.runAfterInteractions延迟到布局稳定。我在内部做了一个简单防护当contentHeight 0时点击头部直接setValue到目标高度不做动画避免错误过渡。第二个坑和鸿蒙的字体渲染相关。鸿蒙默认字体和 iOS/Android 的行高、基线都有差异。长中文文案在鸿蒙上可能比 Android 多渲染半行如果内容区底部没有预留额外的 padding折叠到底后最后一行文字会被硬生生裁掉一半看起来非常糙。解决方式不是改字体大小而是给内容容器底部加上一个基于当前行高的安全间距经验值 4pt 左右并测试系统字体缩放至 1.3 倍时的表现。这个间距在设计稿上可能看不出差别但在折叠动画的“最后一帧”上是决定性细节。第三个坑是内容变化后的高度刷新。业务侧经常会有“展开面板后里面列表额外加载几条数据”的场景。此时内容区真实高度变化了但外层Animated.View的高度被我们锁死成了动画值如果没人告诉它“底下内容变了”面板高度就不会更新。好在我用了内层独立View接收onLayout当子内容增多导致内层高度变化时onLayout会重新触发contentHeight更新后展开状态的目标高度自动跟随。这里要提醒一下onLayout并不是每次都触发如果内层高度没变化它不会无意义地重复回调所以不用担心性能。4. 启动白屏追踪组件不是元凶但组件差点背锅4.1 正片开始首屏白屏的复现路径组件的功能逻辑全部跑通之后我把它集成到一个真实业务页面里做联调。就在这一步碰到了让人头皮发麻的现象从原生壳启动到 React Native 页面首帧渲染出来白屏时间明显变长偶发情况下首页切后台再回来页面会一直白着最多只有顶部原生头部先出来。这个现象正是社区里大家常说的“react native 启动白屏”。我最初也怀疑是自己写的折叠面板拖慢了启动毕竟组件库入口、图片资源都是被我塞进模块里的。但排查到最后发现组件只是其中一个“加速项”真正的根子在于整个鸿蒙启动链路里JS 首帧之前做了太多不该做的事。4.2 一线排查从现象追到启动链路的四个阶段我把启动到首帧的过程拆成了四个阶段逐一统计耗时阶段典型耗时问题表现原生容器初始化300~500ms壳工程和 RN 鸿蒙运行时启动bundle 加载与解析500~800ms包体积大、解析慢JS bundle 执行150~400ms模块顶层副作用拖慢执行首帧渲染React 渲染管线200~600ms字体、图片等资源同步解码卡顿统计出来之后问题就很清楚了白屏的重点不在折叠面板本身而是整个启动链路要在 JS 线程上干太多正事。我在组件库入口写过一个“组件注册中心”每个业务页面不管用不用折叠面板只要 import 了组件库入口模块顶层的new AccordionManager()和一堆静态注册逻辑都会执行一遍。这在启动阶段完全是额外开销。还有一个隐藏点组件库里的箭头图标我一开始用了require(../../assets/arrow.png)这样的静态图片。图片资源被打进 bundle 之后在鸿蒙容器启动首帧阶段如果被同步解码会卡住渲染管线。换成纯代码绘制的矢量箭头用 View 边框旋转实现之后首帧耗时又降了一截。4.3 组件库自身的整改让首帧不再被拖后腿排查完根因我对组件库做了三个层面的整改这些整改逻辑完全可以复用在任何 RN 组件库上首先组件库入口文件保持零副作用。所有内部类都改成惰性单例只有真正使用组件时才去初始化避免业务侧把整个组件树 import 进来时的同步成本。这也是我后来对团队定的纪律组件库的所有模块顶层只允许出现类型定义和常量不允许出现new、不允许立即执行函数。其次静态资源全部改为运行时可替换的 prop。默认图标改成代码绘制业务侧如果需要自定义图标直接传 ReactNode不鼓励业务侧为了一个图标去加载静态图。代码绘制图标的好处很直接bundle 解析阶段不涉及图片解码首帧阶段少一个占用。第三面板内容默认懒挂载。未展开的折叠项其内容区域不渲染真实 children只渲染一个占位结构。这样在页面有多个折叠项时首屏渲染的组件实例数量会大幅减少对首帧的帮助非常明显。// 伪代码示意折叠状态下不让 children 进入渲染树 {expanded ? ( children ) : ( View style{{ height: 0, overflow: hidden }} testIDaccordion-placeholder / )}这个懒挂载策略还带来了一个实际收益不需要展开的内容不会被onLayout测量减少了无意义的布局计算。代价是首次展开时不会有动画“从 0 到高”的过程而是先渲染内容再动画视觉上基本感知不到但性能上值得。5. 收敛成企业级组件库API、测试与接入体验5.1 最终 API 长这样经过前面所有折腾最终对外暴露的 API 收敛得比较干净。核心思路是容器管状态列表项管展示动画细节全部内部消化。Accordion defaultValue{[faq-1]} expandMultiple{false} animated{true} onChange{(expandedIds, changedId) { // 上报埋点或者联动其他组件 }} Accordion.Item idfaq-1 title如何开通企业开发者账号 disabled{false} headerStyle{styles.customHeader} 正文内容可以是任意 React 节点包括列表和图片。 /Accordion.Item Accordion.Item idfaq-2 title折叠面板支持深色模式吗 支持组件内部使用语义色板自动跟随系统切换。 /Accordion.Item /Accordion为了兼容受控场景Accordion的value和onChange是成对出现的业务侧完全可以用useState接管所有展开状态。每个Accordion.Item暴露id作为唯一标识title可以是字符串也可以是自定义 ReactNodeheaderStyle允许业务侧覆盖头部样式但不能破坏基本交互。5.2 测试用例怎么卡住回归企业级组件的底线是“改动之后不能影响存量业务”。我基于react-test-renderer写了一组用例重点覆盖非受控模式下点击头部展开项 ID 是否正确出现在内部状态中互斥模式下展开第二项第一项是否自动收起受控模式下组件不响应内部点击必须等外部更新value再次点击已展开项是否正常收起disabled的项点击后无反应动画播放期间快速点击状态最终是否落位到正确值。一个实际的测试技巧由于onLayout在测试环境中不会自动触发需要在用例里手动调用内容区 View 的onLayout回调mock 一个高度进去否则组件内部会认为内容高度为 0很多分支覆盖不到。代码大概长这样const contentView tree.root.findByProps({ testID: accordion-content }); contentView.props.onLayout?.({ nativeEvent: { layout: { height: 120, width: 300, x: 0, y: 0 } }, });这里也顺手暴露出来一个设计要点代码里的testID不要随手写它们是企业级组件的可维护性的一部分是测试锚点也是未来做 UI 自动化时的钩子。组件库里的testID命名我都是写进文档规范里的。5.3 文档和示例工程的重要性组件写得再稳接入文档跟不上使用成本就会转嫁给调用方的开发同学。我的做法是准备两层接入资料一层是面向纯使用方的 README覆盖安装、基础用法、受控用法、深色模式适配、常见问题五大部分。每段代码都附带一个最小可运行示例确保复制粘贴就能跑。另一层是组件库内部的开发文档详细说明状态模型、动画中断逻辑、测量方案以及为什么useNativeDriver在这里不能开。这一层主要给后续维护者看避免后人为了“性能优化”把动画改坏。示例工程我也专门做了一个 Harmony 平台页面一屏里放了五个不同内容的折叠面板内容包括纯文字、图片列表、异步加载数据三种形态。这个示例工程除了演示功能也兼做性能验证的基准页——每次改动之后我都会在这个页面上过一遍流畅度和白屏耗时。6. 深色模式、低端机与无障碍最后一公里的验收6.1 深色模式适配跟随系统而不是写死颜色折叠面板在深色模式下最容易出的问题是头部背景和内容区背景用了写死的浅色。企业在做深色模式适配时最常见的方案是用useColorScheme()拿到当前色值再动态生成样式。但从组件库角度看更好的做法是把颜色抽象成语义令牌而不是让组件内部到处判断isDark。我把颜色拆成三组背景色、文字色、分隔线色。组件内部全部通过主题对象取值不直接写#fff或#333。这样业务侧接入时哪怕他们的深色主题不是纯黑深灰也可以整体覆写主题令牌而不是在组件外部一层层盖样式。这里有一个容易被忽视的细节折叠面板在展开/收起时内容区和头部区的背景如果完全相同视觉上会糊成一片。我在深色模式下特意让内容区背景比头部区背景低一个亮度层级这样即使动画快速闪过用户也能感知到“这块内容属于哪个面板”。这个细节在浅色模式下差异不明显但在深色模式下非常影响层次感。6.2 低端机的动画与内存考量低端鸿蒙设备上JS 线程本身就不宽裕。折叠面板做高度动画时每一帧都要从 JS 线程计算高度变化再同步给原生层这个开销在低端机上会被放大。实测下来最让我头疼的不是动画本身而是连续快速点击时的内存抖动——每次动画中断重启都会临时创建动画对象如果业务侧快速点十几次内存上涨得肉眼可见。我的处理是动画对象复用不每次new中断时先stopAnimation再重新start避免两个动画实例同时存活。另一个所见即所得的优化是动画时长差异化在低端机上260ms 的动画会出现明显掉帧我通过InteractionManager检测 JS 线程繁忙程度繁忙时把动画时间自动调整为 160ms 并允许降级成“直接切换无动画”。这个降级逻辑不是减配而是保证基本可用性。内存上还有一个大杀器懒挂载。前面提过的“未展开不渲染真实 children”在低端机上的收益比想象中大得多。如果一个页面有六个折叠面板每个面板内容里又有列表和图片全部预渲染会让首帧内存直接爆炸。懒挂载之后整个页面初始渲染的节点树小了一大截内存峰值明显下降。6.3 无障碍与键盘操作企业级组件的验收环节无障碍是绕不开的一关。折叠面板在无障碍树里至少要暴露两个关键信息角色和展开状态。我给Accordion.Item的头部设置的accessibilityRole是button并让accessibilityState.expanded跟随实际展开状态实时变化。这样屏幕阅读器读到头部的时会明确提示“已展开”或“已收起”而不是让用户靠听觉猜。另外系统开启了“减少动态效果”reduce motion时动画时长要响应式缩短或者直接关闭。RN 里可以用AccessibilityInfo.isReduceMotionEnabled()拿到这个设置我在组件内部做了判断AccessibilityInfo.isReduceMotionEnabled().then((enabled) { if (enabled) { // 直接用 setValue 跳过去不做过渡动画 } });键盘操作主要通过onKeyDown事件补齐焦点落在头部时按 Enter 或 Space 触发展开/收起。这个对于企业办公场景很重要很多用户不用触屏而是外接键盘操作平板设备折叠面板如果键盘操作失灵会直接被无障碍评审打回。组件从原型到收敛成企业级版本前后经历了大概三周。除了功能本身我最大的收获其实是对 React Native 鸿蒙化运行时的理解——很多在 iOS/Android 上想当然的组件写法在鸿蒙容器上都会暴露出新的边界。折叠面板的动画、测量、启动加载这几块恰好把最典型的边界都踩了一遍。最后留一个小技巧调试这类高度动画时强烈建议把开发者工具里的动画时长调慢同时打开系统“减少动态效果”对比测试很多肉眼看不到的闪跳问题会在慢速动画下现出原形。如果你也在为鸿蒙上的 RN 组件适配发愁希望这篇记录能提供一点参考方向。