企业官网建设流程全解析

1. 项目背景：在鸿蒙上重写List分组列表

做 React Native 开发的朋友应该都清楚，列表是移动应用里最核心、最高频的交互形态。无论是消息中心、订单页、通讯录还是设置页，几乎都跑不掉“分组 + 列表”的组合。但同样的需求放到鸿蒙平台上，情况就不太一样了。

先说结论：React Native 社区对鸿蒙的适配，在 0.72 版本之后已经比较可用了。某跨平台系统项目需要同时支持安卓、iOS 和鸿蒙三端，小组拿到需求后，我优先把列表这部分打通。因为列表是整个App的信息承载骨架，列表方案不落地，其他业务模块都无从展开。

实际踩下来，鸿蒙版 RN 的整体运行机制和其他平台没有本质区别：依然是 JS 线程跑业务逻辑、原生侧负责渲染和布局。但鸿蒙的 ArkUI 渲染引擎与安卓的 View 体系、iOS 的 UIKit 差异很大，尤其体现在列表组件的滑动性能、缓存回收策略和分组数据的嵌套处理上。如果你之前只写过 Web 端的列表，或者只在安卓上跑过 RN，第一次在鸿蒙上调试分组列表，很容易遇到“代码没报错、但界面就是渲染不出来”这类诡异问题。

本文会完整拆解我在鸿蒙 RN 环境中实现 List 分组列表的整个过程，从数据建模、组件选型到性能优化，再到真机调试中的典型问题。文中所有示例代码均基于 React Native 0.72 及以上版本，配合某公司内部适配的鸿蒙 RN 框架。

注意：截至写作时，鸿蒙 RN 的官方适配包仍处于快速迭代阶段，不同版本间的 API 差异较大。如果你直接用社区版 react-native-harmony，请先确认版本号与 RN 主版本的对应关系，再动手写代码。

2. 分组列表的两种实现路线：SectionList 与 FlatList 深度对比

2.1 SectionList 的适用边界

很多 RN 文档会把 SectionList 定义为“分组列表的官方解决方案”，它自带 section 头、分组索引、粘性头部等能力，API 设计上也确实是为分组场景量身定做的。SectionList 的数据结构天然带层级：sections 数组里每个元素是一个分组对象，内部有 data 数组装条目数据，另可配置 renderSectionHeader 渲染组头。

SectionList 的最大优点是开箱即用，写起来非常贴合业务直觉。但不好的地方在于：它的内部实现基于 VirtualizedList，在 Android 和 iOS 上的表现经过了大量优化，而鸿蒙这块适配层对 VirtualizedList 的嵌套滚动处理还不够成熟。我在模拟项目X中第一次用 SectionList 时，就遇到了在快速滚动时分组的 sticky header 吸顶效果偶尔失效的情况，排查后发现是鸿蒙的滚动容器对 onScroll 事件的节流频率比安卓更高，适配层未能及时同步头部位置导致的。

所以在鸿蒙上，我对 SectionList 的态度是：简单场景、分组数量少（比如不超过 20 组）、每组条目差异不大的时候可以放心用；但一旦涉及大量分组、动态高度、复杂头部交互，建议手动用 FlatList 实现分组渲染，控制力更强。

2.2 为什么最终选用 FlatList

我最终在这套鸿蒙项目里选择了 FlatList 方案，而不是 SectionList，核心原因有两个。

第一个原因是可控性。FlatList 的数据源是一个纯粹的一维数组，每个 item 自行决定渲染成组头还是内容行，或者两者混合。这样分组的边界、组间的间距、组头的吸附逻辑完全由开发者掌握，不依赖适配层对 SectionList 内部复杂状态的管理。

第二个原因是性能调优的精度。FlatList 暴露的 Props 更底层、更丰富，比如 getItemLayout、maxToRenderPerBatch、windowSize、removeClippedSubviews 这些参数可以直接控制渲染窗口和回收策略。对于鸿蒙这种还处于适配爬坡期的平台，这类底层参数就是救命稻草。如果直接依赖 SectionList，遇到性能问题往往只能干瞪眼，因为内部机制不好干预。

简单总结一下我的选型标准：

• 分组数量少且固定，优先 SectionList，代码简洁；
• 分组数量大、分组内数据动态变化、需要精细控制渲染，优先 FlatList；
• 鸿蒙平台建议优先 FlatList，除非业务极其简单。

2.3 鸿蒙适配层对列表组件的特殊影响

提到鸿蒙的适配，必须多说一句。鸿蒙侧的 RN 框架是通过一个桥接层把 JS 组件映射到 ArkUI 的 Native 组件上的，例如 View 映射到 Column/Stack、ScrollView 映射到 Scroll、FlatList 则映射到 ArkUI 的 List。这个映射层目前最大的挑战在于：ArkUI 的 List 组件有一套自己的缓存和复用机制，和 RN 的 VirtualizedList 的回收机制之间存在协调成本。

常见的表现是：快速滑动时，某些 item 会出现短暂的白屏闪动；或者在列表底部加载更多时，新数据插入顶部等操作会引起整体偏移抖动。这些问题的深层原因，大多是 ArkUI 列表的 item 回收时机与 RN VirtualizedList 预期的渲染窗口不完全一致。

明白这层关系后，我在实现分组列表时有两个基本方针：

1. 尽量让一个 item 内只承载单一职责，避免在 cell 内嵌套另一个 FlatList 或 ScrollView，因为嵌套滚动在鸿蒙适配层上的表现非常不稳定；
2. 对可能变更高度的 cell 要格外小心，因为 ArkUI 的布局引擎对高度变化后的重新测量开销明显高于安卓。

3. 分组数据建模：接口返回的“一维数组”如何转成分组结构

3.1 后端数据的典型形态

大多数情况，后端接口返回的数据并不是现成的分组格式，而是一个扁平的列表，每条记录带一个分组标识字段。举个例子，一个任务清单接口可能返回：

[ { id: 't1', title: '早会纪要', category: '工作', time: '2026-01-12 09:30' }, { id: 't2', title: '跑步', category: '生活', time: '2026-01-12 08:00' }, { id: 't3', title: '周报', category: '工作', time: '2026-01-11 18:00' }, { id: 't4', title: '买菜', category: '生活', time: '2026-01-11 17:00' }, ]

像这种结构，你可以直接在前端做“按时间分组”或“按类别分组”。做分组前，你先要明确两个维度：

• 分组键：用什么字段来分组（category，还是按日期的年月日）；
• 组内排序：同一组内的条目按什么规则排（时间倒序、ID倒序等）。

3.2 从扁平数据构建 sections 结构

最直接的做法是遍历数组，动态构造一个 Map，以分组键作为 key，收集条目数组。实现起来很简单：

const groupBy = (list, keySelector) => { const map = new Map(); list.forEach((item) => { const key = keySelector(item); if (!map.has(key)) { map.set(key, []); } map.get(key).push(item); }); return Array.from(map.entries()).map(([key, items]) => ({ key, items, })); };

这段代码做完之后，你得到的 sections 数组长这样：

// 按 category 分组 [ { key: '工作', items: [t1, t3] }, { key: '生活', items: [t2, t4] }, ]

到这里，数据是可以直接喂给 SectionList 了，但如果要喂给 FlatList，你还得进一步做“扁平化”。

3.3 扁平化策略：如何区分 header 行与内容行

用 FlatList 实现分组渲染，核心思想是把组头和组内条目都视为一个“渲染单元”，只不过类型不同。我习惯给每个 entry 附加一个 type 字段来区分行类型：

const buildRows = (sections) => { const rows = []; sections.forEach((section) => { rows.push({ type: 'header', title: section.key }); section.items.forEach((item) => { rows.push({ type: 'row', data: item }); }); }); return rows; };

这个 buildRows 的产物是：

[ { type: 'header', title: '工作' }, { type: 'row', data: t1 }, { type: 'row', data: t3 }, { type: 'header', title: '生活' }, { type: 'row', data: t2 }, { type: 'row', data: t4 }, ]

这样一来，FlatList 的 renderItem 里只需要判断 type，分别渲染组头或内容行即可。这种方案的巨大优点是：你完全控制了分组行的位置、间距、样式，不受 SectionList 内部逻辑的限制。

另外，建议在 buildRows 阶段就生成并缓存行高。因为 FlatList 在鸿蒙上的性能瓶颈很大程度来自动态高度测量，如果我们能提前告诉它每一行的高度（通过 getItemLayout），渲染性能会有质的提升。这个点后面细讲。

3.4 数据更新时的处理技巧

分组列表的数据不会永远不变。用户下拉刷新，或者加载更多分页，都会改变数据。实践中最容易犯的错误是：每次拿到新数据都全量重新 buildRows，导致 FlatList 的 data 引用变化，整个列表可能从顶部重新渲染。

我的处理方式是：先判断新数据与旧数据的差异是增量还是全量。如果是下拉刷新，直接替换整体数据并让列表滚回顶部；如果是加载更多，则在当前 sections 的最后一组追加 items，再走 buildRows。

还有一点值得注意：如果分组键是按日期生成（比如“今天”、“昨天”、“更早”），那么跨天时日期组的名称会变化。因为日期是动态的，所以每次刷新都建议重新计算分组键，同时用 useMemo 包一层去重逻辑，避免不必要的重复渲染。

4. FlatList 分组列表的完整实现：从 renderItem 到性能优化

4.1 基础组件结构

下面是一段可以直接跑通的基础分组列表实现，基于 RN 0.72 的 API：

import React, { useCallback, useMemo } from 'react'; import { FlatList, Text, View, StyleSheet } from 'react-native'; const GroupList = ({ rawData }) => { const rows = useMemo(() => { const sections = groupBy(rawData, (item) => item.category); return buildRows(sections); }, [rawData]); const renderItem = useCallback(({ item }) => { if (item.type === 'header') { return ( <View style={styles.header}> <Text style={styles.headerTitle}>{item.title}</Text> </View> ); } return ( <View style={styles.row}> <Text style={styles.rowTitle}>{item.data.title}</Text> <Text style={styles.rowTime}>{item.data.time}</Text> </View> ); }, []); const keyExtractor = useCallback((item, index) => { return item.type === 'header' ? `header-${item.title}` : `row-${item.data.id}`; }, []); const getItemLayout = useCallback((data, index) => { const item = data[index]; const height = item.type === 'header' ? HEADER_HEIGHT : ROW_HEIGHT; const offset = data.slice(0, index).reduce((acc, cur) => { return acc + (cur.type === 'header' ? HEADER_HEIGHT : ROW_HEIGHT); }, 0); return { length: height, offset, index }; }, []); return ( <FlatList data={rows} renderItem={renderItem} keyExtractor={keyExtractor} getItemLayout={getItemLayout} showsVerticalScrollIndicator={false} /> ); };

<- 这里的 getItemLayout 用了 reduce，如果列表很长，每次调用都做全量计算，性能会打折扣。请用前缀和数组替代。-->

实际项目中，如果列表条目在几千行以上，getItemLayout 里用 reduce 是不可接受的。它会让 FlatList 在滚动时反复计算 offset，产生性能问题。优化方案是提前建一个 prefix 数组，存下每个 index 对应的 offset 和 height。

const { heights, offsets } = useMemo(() => { const heights = rows.map((row) => (row.type === 'header' ? HEADER_HEIGHT : ROW_HEIGHT)); const offsets = []; let acc = 0; heights.forEach((h, i) => { offsets.push(acc); acc += h; }); return { heights, offsets }; }, [rows]); const getItemLayout = useCallback((data, index) => { return { length: heights[index], offset: offsets[index], index }; }, [heights, offsets]);

这样 getItemLayout 的复杂度从 O(n) 降到了 O(1)，在几千行的列表中效果尤其明显。

4.2 固定行高与动态行高的取舍

在设计分组列表时，行高方案非常关键。我分两类场景来说。

如果业务上组头和内容行的高度都是固定的，比如组头 40 像素、内容行 60 像素，那我建议就用固定的常量，配合上面那种 prefix 数组方案。这样做的好处是，FlatList 不需要真实的渲染也能精确知道每个元素的位置和高度，滚动条的位置计算、滑动跳转的表现都非常稳定。这种方案在鸿蒙上最稳，也是帧率最容易达到 60fps 的。

如果内容行的高度是动态的，比如一个卡片式列表，每张卡片的文字行数不同，那么固定高度方案就不适用了。此时要么放弃 getItemLayout 让 FlatList 动态测量，要么在渲染前做一次内容审核，预估出每行的近似高度。这两种方案在鸿蒙上都有明显代价：动态测量在快速滑动时会产生明显的卡顿和跳动。

如果非要做动态高度，我的建议是：行高不要频繁变化。例如允许文字两行、三行，但不要用“根据字体自适应高度”这种策略。你可以在数据层面对文本做截断，固定最大行数，再配合 onLayout 在初次渲染时把真实高度记录下来。这样大部分 index 的高度可以提前确定，只有少量变化。

4.3 renderItem 的优化：避免 inline 函数与重渲染

renderItem 内部渲染的每一个 cell 都是一个原生组件的组合体。在 FlatList 的渲染机制中，一个 item 从 JS 层到原生层的传递要经过跨线程通信，如果 renderItem 每次都返回一个新的组件树，通信开销会成倍增加。

我习惯把组头和内容行拆成独立的子组件，并用 React.memo 包裹，这样单个 cell 的props变化时，只重绘变化的那一部分。

const HeaderItem = React.memo(({ title }) => ( <View style={styles.header}> <Text style={styles.headerTitle}>{title}</Text> </View> )); const RowItem = React.memo(({ data }) => ( <View style={styles.row}> <Text style={styles.rowTitle}>{data.title}</Text> <Text style={styles.rowTime}>{data.time}</Text> </View> ));

然后 renderItem 里只需要做类型判断，直接分发到对应组件：

const renderItem = useCallback(({ item }) => { if (item.type === 'header') { return <HeaderItem title={item.title} />; } return <RowItem data={item.data} />; }, []);

这样做的收益在鸿蒙上比安卓更明显，因为鸿蒙的桥接通信开销本就更高，减少 JS 侧的重复渲染就显得尤为关键。

4.4 分组索引与快速跳转

很多通讯录类 App 需要在右侧显示字母索引条，点击后跳转到对应分组。在鸿蒙 RN 中，这一功能需要额外的原生支持，因为 ArkUI 的 ScrollBar 是原生的，没法直接接 JS 事件。

我当时的方案是：在 FlatList 右侧叠加一个用绝对定位的 View，渲染字母列表，再通过 scrollToIndex 定位到对应组头行的 index。关键是要维护一个分组名到 index 的映射关系，可以在 buildRows 阶段一并生成：

const buildIndexMap = (rows) => { const map = {}; rows.forEach((row, index) => { if (row.type === 'header') { map[row.title] = index; } }); return map; };

点击字母时调用：

listRef.current.scrollToIndex({ index: indexMap[letter], animated: true });

这里有个大坑需要提醒：如果 FlatList 的列表非常长，scrollToIndex 在鸿蒙上可能会出现定位不准的情况，尤其是列表中还包含动态高度 item 的时候。我一个项目里就出现过点击字母后定位到错误行的现象，排查后发现是 getItemLayout 传的 offset 与实际渲染高度不一致导致的。后来我统一改成了固定高度，问题就没再出现。

如果无法固定高度，至少要在 onScrollToIndexFailed 回调里做兜底处理：

onScrollToIndexFailed={({ index, averageItemLength }) => { listRef.current.scrollToOffset({ offset: index * averageItemLength, animated: true, }); }}

这个兜底方案虽然没有精确到像素，但至少能保证用户点击索引后不会“纹丝不动”。

5. 下拉刷新与加载更多：分组列表的完整交互闭环

5.1 下拉刷新的正确接入方式

FlatList 自带 RefreshControl 相关的 props：refreshing 和 onRefresh。在鸿蒙适配层中，这两个 props 已经可以正常工作，但要注意下拉刷新的视觉样式。

鸿蒙原生下拉刷新的 UI 样式与安卓的 Material 风格不同，RN 适配层默认使用的是鸿蒙系统自带的下拉刷新组件。这本身没有太大问题，但如果你在业务中自定义了刷新指示器（比如一只眨眼的猫），需要确保自定义组件的布局是绝对定位并且悬浮在列表上方，否则它会跟随列表滚动。

我的建议是：早期版本先使用系统默认的下拉刷新，不要过度自定义，先把列表的数据流和刷新逻辑跑通。等基础功能稳定后再做视觉升级。某跨平台系统项目里我就是先用的默认样式上线第一版，后期加了自定义动画，因为前面已经验证过列表本身的稳定性，排查自定义刷新问题时不需要再去怀疑列表组件。

5.2 加载更多的触发机制与防抖

FlatList 提供了 onEndReached 回调，在滚动接近底部时触发。这个 API 在鸿蒙上的表现有个小问题：触发频率比安卓高，如果不做防抖，容易出现重复请求。

我的处理方案是给加载更多加一个锁：

const [loadingMore, setLoadingMore] = useState(false); const handleLoadMore = useCallback(() => { if (loadingMore) { return; } const curLen = dataRef.current.length; const total = totalCountRef.current; if (curLen >= total) { return; } setLoadingMore(true); fetchNextPage() .then((newData) => { // 追加到数据源，并更新 rows }) .finally(() => { setLoadingMore(false); }); }, [loadingMore]);

另外，onEndReachedThreshold 这个参数也值得调。它表示距离底部多远时触发回调，默认是 0.5（即列表剩一半屏幕高度时触发）。鸿蒙上我习惯把它设置为 0.2 甚至 0.1，这样触发时机更靠底部，避免在快速滑动时提前请求，浪费带宽。

5.3 分页数据插入时如何保持视觉稳定

加载更多之后，新数据追加到当前最后一个分组，或者是新增了一个分组。理想情况下，用户在滚动到底部后看到的是新内容从底部逐渐出现，而不是整体列表跳动。

但鸿蒙 ArkUI 列表组件在数据源发生变化时，偶尔会重置滚动位置。避免这个问题的最有效办法是：用滚动偏移量来反向校准滚动位置，而不是强行使用 scrollToIndex。

const handleLoadMore = async () => { const offset = scrollOffsetRef.current; const firstVisibleIndex = Math.floor(offset / ROW_HEIGHT); await fetchNextPage(); requestAnimationFrame(() => { listRef.current.scrollToOffset({ offset: firstVisibleIndex * ROW_HEIGHT, animated: false, }); }); };

先记录当前偏移量，数据更新后立刻恢复。这样用户观感上是“平滑地接上了新内容”，而不是从顶部跳下来。这个方法在安卓上不一定需要，但在鸿蒙上几乎成了标配。

5.4 刷新与加载更多的并发控制

最容易被忽视的是：下拉刷新和加载更多同时触发。比如用户在下拉刷新的瞬间，列表又触发了 onEndReached，两股请求并发返回，数据源容易错乱。

我的处理方式是用一个简单的状态机：

• 处于“加载中”状态时，onRefresh 和 onLoadMore 都直接 return；
• 刷新完成前，不触发加载更多；加载更多完成前，不触发刷新；
• 刷新完成时，清空当前列表，直接替换新数据；加载更多完成时，追加数据。

用代码表示：

const [listStatus, setListStatus] = useState('idle'); // 'idle' | 'refreshing' | 'loadingMore'

这个状态机在鸿蒙上尤其重要。因为 RN 鸿蒙适配层对滚动事件的派发有时会有滞后，如果JS侧没有状态锁，很容易收到重复的 onEndReached 触发。

6. 性能调优实录：从卡顿到流畅的三板斧

6.1 关闭不必要的渲染窗口

FlatList 有几个控制渲染窗口的核心参数，理解它们的内涵比知道它们的存在更重要。

• windowSize：单位是屏幕高度，表示当前可视区域上下各保留多少屏幕高度的内容用于渲染。默认是 21（理解成当前屏幕上方10个屏、下方10个屏都渲染）。这个值越大，滑出屏幕的内容越晚回收，内存占用越高。鸿蒙上我设成 5 就能兼顾流畅度和内存。

• maxToRenderPerBatch：每帧最多渲染多少个 item。默认是 10，在鸿蒙上适度调高到 15 可以让快速滑动时内容补充更及时，但也会增加JS线程负担，需要实测调整。

• removeClippedSubviews：在安卓上，这个属性默认开启，负责回收屏幕外的子视图。鸿蒙上这个属性必须显式开启，才能在长列表滚动时释放不可见图层的渲染资源。

<FlatList windowSize={5} maxToRenderPerBatch={15} removeClippedSubviews ... />

这三个配置组合起来，是我在鸿蒙上让列表从“滚动掉帧”到“基本流畅”的关键。不过我不建议直接照搬，不同设备、不同列表条目复杂度，最优参数都不一样。比较好的调试方式：先用默认参数跑一版，在真机上打开 dev menu 的 Perf Monitor 看帧率，再逐个调参对比效果。

6.2 分离高频变更状态

列表数据里如果有“点赞数”、“阅读数”这类高频变化的字段，尽量不要让这些字段直接参与 FlatList 的 data 渲染。因为每次变更都会触发 FlatList 对整个可见区域做重渲。

我的做法是把这类动态数据提升到 cell 内部管理，或者用全局状态库做局部更新。比如点赞状态放在 store 里，cell 内部通过 useSelector 精确订阅，而不是从父组件的 data 数组里透传。

这里要特别强调：在鸿蒙的 RN 适配层，这种“局部刷新”的能力还依赖原生列表组件的 diff 算法。如果原生侧不理解某个 prop 的变化只影响单个 cell，它可能还是会触发整个可视区域重建。所以最稳妥的方案是：把高频变化的字段独立成一个自定义事件的监听器，在 cell 内监听对应 id 的事件来更新 UI。

6.3 长列表的内存回收策略

分组列表最怕的是内存膨胀。尤其是每个 cell 里含有 Image 组件时，图片缓存在内存中会快速堆积。鸿蒙上这个问题更明显，因为 ArkUI 的内存回收策略比安卓激进，如果你不及时释放不可见图层的图片引用，系统可能直接回收整个列表的渲染上下文。

解决办法很简单：在 FlatList 的 onViewableItemsChanged 回调里，获取当前可见的 item 集合，然后对不可见 item 的图片做降采样或置空。核心代码如下：

const onViewableItemsChanged = useRef(({ viewableItems }) => { const visibleIds = viewableItems.map((viewable) => viewable.key); // 将 visibleIds 之外的图片资源释放 }).current; <FlatList onViewableItemsChanged={onViewableItemsChanged} viewabilityConfig={{ itemVisiblePercentThreshold: 50 }} ... />

注意 viewableItems 里的 key 来自 keyExtractor 的返回值，所以 keyExtractor 一定要稳定且唯一。否则回收策略会命中错误的 cell。

6.4 实测数据参考

我基于某跨平台系统项目的真实数据做过一次压测：3000 条数据，分成 12 组，每组平均 250 条。使用固定行高方案，配置上述优化参数后，在鸿蒙真机上滑动帧率基本稳定在 55-60fps，内存峰值比优化前降低了约 30%。如果改用动态行高，帧率会下降到 45fps 左右，快速滑动时偶尔出现白屏。

所以我强烈建议：鸿蒙上的分组列表，优先把布局设计成固定行高。虽然这会牺牲一些视觉灵活性，但在当前适配阶段，稳定压倒一切。

7. 真机调试与常见问题速查

7.1 鸿蒙设备上调试 RN 项目的链路

调试鸿蒙 RN 项目和安卓大同小异，核心都是通过 Metro 服务器加载 JS bundle。但有几点差异需要注意：

• 鸿蒙运行的模拟器相关调试命令与安卓不同，需要通过 hdc 命令连接设备；
• 启动 Metro 后，需要在鸿蒙侧的开发设置中手动指定 Metro 服务器的地址和端口（默认 8081）；
• 连接真机时，需要确保鸿蒙设备的网络和服务端处于同一局域网，否则无法加载 bundle。

如果你遇到“无法连接 Metro”“页面一直显示加载中”，优先排查这三件事：设备是否在同一网段、adb/hdc 是否识别设备、Metro 端口是否被占用。

7.2 典型问题：Item 渲染空白

我在鸿蒙上遇到最多的一个问题是：FlatList 渲染出来的页面，前几个 item 正常，往下稍微一拖，下面的 item 全部白屏，控制台无任何报错。

这个问题的根源往往不在数据，而在渲染窗口的高度计算。ArkUI 的 List 在初次布局时如果没有获取到准确的 contentSize，就不会继续请求更多的 item。

排查思路：

1. 检查 FlatList 是否有合法的父容器高度，不要放在 flex: 1 都没设置的 View 里；
2. 检查内容区域是不是被绝对定位或 zIndex 遮挡；
3. 确认 getItemLayout 的 offset 计算没有越界。

如果确认父容器没问题，还有一个隐藏坑：鸿蒙上 FlatList 的初始渲染数量可能比预期更少。这时可以显式设置 initialNumToRender，比如设为 20，强制首屏渲染更多 item。

7.3 典型问题：分组头吸顶失效

SectionList 自带 stickySectionHeadersEnabled，但在鸿蒙上这个效果时好时坏。如果你用的就是 SectionList，遇到吸顶失效，优先检查 ArkUI 的滚动容器是否有额外的 margin/padding。

如果改用 FlatList 方案，吸顶需要自行实现。简单做法是：监听 onScroll 获取当前滚过的 section index，在列表上方渲染一个“悬浮组头”，内容随着滚动变化。但这种实现方案在滚动频率很高的场景下，JS 与原生通信可能成为瓶颈，需要谨慎使用。

如果产品经理只要“组头固定显示当前分组”的需求，而不要求吸顶动画，我建议直接用这种悬浮方案，效果简单直接，性能消耗远低于实时位置计算。

7.4 典型问题：列表跳转后定位不准

前面提过，这个问题的根因几乎都是高度计算和真实渲染不一致。解决方向有两个：

1. 行高必须稳定。如果一定要动态高度，必须在数据进入列表前统一计算，不要把计算交给渲染期；
2. 如果列表数据在渲染过程中发生了变化（比如图片加载完成导致文字换行、cell 高度变化），那么之前缓存的 offset 就会全部失效。此时可以主动重新构建 offsets 前缀表，或者直接放弃 scrollToIndex，改用 scrollToOffset 配合模糊计算。

7.5 问题速查表

这张表是我日常调试中最常翻出来的内容。遇到问题先按表排查一遍，基本能覆盖 80% 的坑。

8. 后续扩展与个人体会

在鸿蒙上实现 React Native 分组列表，说难不难，说简单也不简单。核心障碍不在 RN 本身，而在适配层的成熟度。从实践看，只要严格遵循“固定行高优先、渲染窗口克制、数据流状态控制”这三个原则，列表功能就能稳定落地。

如果后续需要扩展，我建议往这几个方向走：一是分组头吸顶的沉浸式体验定制，二是列表项左滑操作菜单，三是无限滚动与列表回收策略的深度结合。这几个方向在鸿蒙上都有各自的适配坑，但也是让列表真正具备产品级体验的关键。

我在实际项目中还有一个经验想分享：不管文档写得多好看，鸿蒙 RN 的适配方案最终都要靠真机验证。模拟器上流畅不等于真机流畅，内存回收策略和滚动表现在不同设备上的表现差异非常明显。建议在需求排期时，多留一点时间专门做真机性能测试和调优，这部分投入非常值得。

如果你正准备在鸿蒙上做 RN 列表开发，希望这份实战笔记能帮你少走几个弯路。列表是整个应用的地基，把地基打稳了，上面的楼才好盖。