从入门小白到精通，玩转 React Native 鸿蒙跨平台开发：FlatList 高性能列表组件

对于新手而言，FlatList 是 RN 鸿蒙官方推荐、必须吃透的高性能核心列表组件，它完美适配鸿蒙系统，专门解决「长列表数据展示」的性能问题，语法简单、上手快，无复杂原生配置，所有代码均可直接复制运行。本文专为零基础小白打造，全程只讲「核心基础用法 + 高频实战场景」，剔除所有冗余进阶内容，吃透本文就能搞定 RN 鸿蒙开发中 99% 的列表开发需求。

前置说明：RN 鸿蒙的 FlatList 与原生 React Native 的 FlatList 用法完全一致，鸿蒙端做了完美适配，学会即能跨鸿蒙 / 安卓 /iOS 三端复用代码，无额外学习成本；且 FlatList 已经替代了老旧的 ListView 组件，新手无需学习 ListView，直接上手 FlatList 即可。

一、新手必懂：FlatList 核心基础认知

1.1 为什么要用 FlatList ？不用普通 View 循环渲染？

新手第一个疑问：我用 map 循环遍历数组，用 View 包裹内容也能做列表，为什么还要学 FlatList？✅ 核心答案：普通 View 循环渲染「长列表必卡顿」，FlatList 天生高性能

普通 View 循环：一次性渲染列表中所有数据项，哪怕数据有 1000 条，页面加载时会全部渲染，鸿蒙真机 / 模拟器会出现页面卡顿、加载慢、内存溢出，数据越多越卡；
FlatList 高性能核心：采用「按需渲染 + 组件复用」机制，只渲染当前屏幕可见的列表项，屏幕外的内容不会渲染，滑动时再动态加载，哪怕列表有 10000 条数据，依然流畅不卡顿，内存占用极低。

1.2 FlatList 核心定义

FlatList 是 React Native 鸿蒙内置的高性能滚动列表组件，是专门为「海量数据、长列表展示」设计的基础组件，核心作用就是：高效渲染结构化的列表数据。

二、FlatList 核心属性速查表

这是本文核心重点之一！为零基础新手量身整理，只保留「必用、高频、零基础能看懂」的核心属性，剔除所有冷门、进阶、无用的配置项，鸿蒙端完美适配无差异，新手建议收藏，开发时直接对照使用，这就是 FlatList 的「开发速查手册」。

重中之重：FlatList 有 2 个必写属性，少一个列表都绝对不会显示，新手记牢！

属性分类	属性名	必填	取值 / 写法	核心说明	鸿蒙适配注意点
✅ 核心必写	data	✔️	数组（如：[{},{},{}]）	列表的「数据源」，列表要展示的所有数据都存在这里	鸿蒙无差异，支持任意格式数组
✅ 核心必写	renderItem	✔️	({item}) => < 列表项布局 />	列表「渲染函数」，定义每条列表项的 UI 样式和展示内容，`item` 就是当前遍历的数组元素	鸿蒙完美兼容，写法和 RN 原生一致
高频常用	keyExtractor	✔️（推荐）	(item, index) => 唯一标识	给每条列表项设置「唯一 key 值」，用于组件复用，提升性能，避免列表错乱	鸿蒙端必须设置，否则会有性能警告
高频常用	style	❌	StyleSheet 样式对象	给整个列表设置样式（宽高、背景色、内边距等）	列表默认占满宽度，建议设置 height
高频常用	itemSeparatorComponent	❌	() => < 分割线组件 />	列表项之间的「分割线」，开发中必用，提升列表美观度	鸿蒙支持任意 View 作为分割线，极简好用
高频常用	onPress （item 内）	❌	() => {}	列表项「点击事件」，开发中最高频的列表交互	鸿蒙端支持防抖，点击无延迟，体验好
基础样式	horizontal	❌	true / false	是否横向滚动列表，默认 false（纵向）	横向列表需给列表项设置固定宽度
基础样式	showsVerticalScrollIndicator	❌	true / false	是否显示纵向滚动条，默认 true	鸿蒙端隐藏滚动条更美观，建议设为 false
基础样式	showsHorizontalScrollIndicator	❌	true / false	是否显示横向滚动条，默认 true	同上，横向列表建议隐藏

三、3 个阶梯式案例

通用前置：所有 FlatList 案例，数据源统一用「模拟业务数据」（商品列表 / 消息列表），新手可直接替换成自己的业务数据，无缝衔接开发。

案例 1：基础最简版 - FlatList 实现基础纵向列表

纯基础写法，只保留「2 个必写属性 + 推荐属性 keyExtractor」，实现最基础的列表展示，新手第一个要写的 FlatList 代码，理解这个案例，就理解了 FlatList 的核心逻辑。

import React from 'react';
import { View, Text, FlatList, StyleSheet } from 'react-native';

const goodsList = [
  { id: 1, name: '鸿蒙智能手环', price: '¥199' },
  { id: 2, name: 'RN开发实战教程', price: '¥89' },
  { id: 3, name: '鸿蒙生态蓝牙耳机', price: '¥299' },
  { id: 4, name: '跨平台开发笔记本', price: '¥59' },
  { id: 5, name: '鸿蒙系统定制贴膜', price: '¥19' },
  { id: 6, name: 'React Native实战手册', price: '¥79' },
];

const BasicFlatList = () => {
  const renderGoodsItem = ({ item }) => {
    return (
      <View style={styles.itemBox}>
        <Text style={styles.itemName}>{item.name}</Text>
        <Text style={styles.itemPrice}>{item.price}</Text>
      </View>
    );
  };

  return (
    <View style={styles.container}>
      <FlatList
        data={goodsList} // 必写：绑定数据源
        renderItem={renderGoodsItem} // 必写：绑定渲染函数
        keyExtractor={(item) => item.id.toString()} // 推荐：唯一key值，item.id转字符串
        style={styles.listStyle}
      />
    </View>
  );
};

// 样式配置
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#f5f5f5',
    padding: 10,
  },
  listStyle: {
    width: '100%',
  },
  itemBox: {
    backgroundColor: '#fff',
    padding: 15,
    marginBottom: 8,
    borderRadius: 6,
  },
  itemName: {
    fontSize: 16,
    color: '#333',
  },
  itemPrice: {
    fontSize: 14,
    color: '#ff4444',
    marginTop: 5,
  },
});

export default BasicFlatList;

案例 2：开发高频版 - 带分割线 + 美化样式的完整列表

在基础版的基础上，增加「列表分割线、隐藏滚动条、优化样式」，这是 实际开发中最常用的标准写法，代码只在基础版上少量修改，无新增复杂逻辑，美观度和实用性拉满，新手直接复制到项目中即可使用。

import React from 'react';
import { View, Text, FlatList, StyleSheet } from 'react-native';

// 模拟数据源
const goodsList = [
  { id: 1, name: '鸿蒙智能手环', price: '¥199', desc: '超长续航 鸿蒙互联' },
  { id: 2, name: 'RN开发实战教程', price: '¥89', desc: '零基础到精通' },
  { id: 3, name: '鸿蒙生态蓝牙耳机', price: '¥299', desc: '无感延迟 降噪' },
  { id: 4, name: '跨平台开发笔记本', price: '¥59', desc: '加厚纸张 书写顺滑' },
  { id: 5, name: '鸿蒙系统定制贴膜', price: '¥19', desc: '高清防爆 全屏覆盖' },
  { id: 6, name: 'React Native实战手册', price: '¥79', desc: '实战案例 源码解析' },
];

const BeautyFlatList = () => {
  // 列表项渲染函数
  const renderGoodsItem = ({ item }) => {
    return (
      <View style={styles.itemBox}>
        <Text style={styles.itemName}>{item.name}</Text>
        <Text style={styles.itemDesc}>{item.desc}</Text>
        <Text style={styles.itemPrice}>{item.price}</Text>
      </View>
    );
  };

  const renderSeparator = () => {
    return <View style={styles.separator} />;
  };

  return (
    <View style={styles.container}>
      <FlatList
        data={goodsList}
        renderItem={renderGoodsItem}
        keyExtractor={(item) => item.id.toString()}
        ItemSeparatorComponent={renderSeparator}
        showsVerticalScrollIndicator={false} 
        style={styles.listStyle}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#f5f5f5',
    padding: 10,
  },
  listStyle: {
    width: '100%',
  },
  itemBox: {
    backgroundColor: '#fff',
	padding: 15,
	borderRadius: 6,
  },
  itemName: {
    fontSize: 16,
    color: '#333',
    fontWeight: '500',
  },
  itemDesc: {
    fontSize: 12,
    color: '#999',
    marginTop: 3,
  },
  itemPrice: {
    fontSize: 15,
    color: '#ff4444',
    marginTop: 8,
  },
  separator: {
    height: 8, // 分割线高度=列表项间距
    backgroundColor: '#f5f5f5',
  },
});

export default BeautyFlatList;

案例 3：交互核心版 - 带列表项点击事件的列表

列表的核心交互就是「点击列表项」—— 比如点击商品进入详情页、点击消息进入聊天页、点击条目执行对应逻辑。这个案例在美化版的基础上，新增列表项点击事件，是开发中100% 会用到的写法，代码极简，新手轻松掌握，也是 FlatList 的核心交互能力。

import React from 'react';
import { View, Text, FlatList, StyleSheet, Alert, TouchableOpacity } from 'react-native';

// 模拟数据源
const goodsList = [
  { id: 1, name: '鸿蒙智能手环', price: '¥199', desc: '超长续航 鸿蒙互联' },
  { id: 2, name: 'RN开发实战教程', price: '¥89', desc: '零基础到精通' },
  { id: 3, name: '鸿蒙生态蓝牙耳机', price: '¥299', desc: '无感延迟 降噪' },
];

const ClickFlatList = () => {
  // 定义列表项点击事件 - 核心新增
  const handleItemClick = (item) => {
    // 点击后可执行：跳转详情页、弹窗提示、请求接口等逻辑
    Alert.alert('列表项被点击', `你选择了：${item.name}，价格：${item.price}`);
  };

  // 列表项渲染函数 - 用TouchableOpacity包裹实现点击
  const renderGoodsItem = ({ item }) => {
    return (
      <TouchableOpacity 
        style={styles.itemBox}
        onPress={() => handleItemClick(item)} // 绑定点击事件，传入当前项数据
        activeOpacity={0.8} // 点击时的透明度，提升鸿蒙端交互体验
      >
        <Text style={styles.itemName}>{item.name}</Text>
        <Text style={styles.itemDesc}>{item.desc}</Text>
        <Text style={styles.itemPrice}>{item.price}</Text>
      </TouchableOpacity>
    );
  };

  // 分割线
  const renderSeparator = () => {
    return <View style={styles.separator} />;
  };

  return (
    <View style={styles.container}>
      <FlatList
        data={goodsList}
        renderItem={renderGoodsItem}
        keyExtractor={(item) => item.id.toString()}
        ItemSeparatorComponent={renderSeparator}
        showsVerticalScrollIndicator={false}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#f5f5f5',
	padding: 10,
  },
  itemBox: {
    backgroundColor: '#fff',
	padding: 15,
	borderRadius: 6,
  },
  itemName: { fontSize:16, color:'#333' },
  itemDesc: { fontSize:12, color:'#999', marginTop:3 },
  itemPrice: { fontSize:15, color:'#ff4444', marginTop:8 },
  separator: { height:8, backgroundColor:'#f5f5f5' },
});

export default ClickFlatList;

四、FlatList 3 个高性能优化技巧（

FlatList 本身就是「高性能列表组件」，但如果写法不当，依然会出现轻微卡顿、列表错乱等问题。这 3 个优化技巧，全部是零基础能看懂、一行代码就能实现的基础优化，无任何进阶操作，优化后列表在鸿蒙端会更流畅

✅ 优化 1：必写 keyExtractor，杜绝列表错乱

这是最重要的优化，也是最容易忽略的点。keyExtractor 给每条列表项设置唯一标识，FlatList 会根据这个标识复用组件，避免滑动时列表项内容错乱、重复渲染。

写法：keyExtractor={(item) => item.id.toString()} （优先用数据自身的唯一 id，不要用 index 下标）

✅ 优化 2：给列表项设置「固定高度」

FlatList 在渲染时，如果列表项高度不固定，会额外计算高度，增加性能消耗。给列表项设置固定的 height 样式，鸿蒙端会直接渲染，无需计算，滚动更流畅。

写法：在 itemBox 样式中添加 height: 100 即可。

✅ 优化 3：隐藏滚动条，减少渲染开销

滚动条本身也是一个组件，会占用少量渲染资源。隐藏滚动条不仅能提升一点点性能，还能让列表界面更美观，鸿蒙端体验更好。

写法：showsVerticalScrollIndicator={false}

五、避坑指南：6 个高频基础坑

FlatList 是入门阶段「踩坑最多」的组件，但所有坑都是基础坑、低级坑，没有复杂的进阶坑。整理了开发中最容易遇到的 6 个高频问题

✘ 坑 1：写了 FlatList 代码，页面一片空白，列表完全不显示 → ✔ 解决方案：检查是否写了 data 和 renderItem 这 2 个必写属性！少一个都不会显示，第一大坑，重中之重；
✘ 坑 2：列表能显示，但滑动时内容错乱、重复渲染 → ✔ 解决方案：添加 keyExtractor 属性，给每条列表项设置唯一 key 值，不要用 index 作为 key；
✘ 坑 3：分割线不显示 → ✔ 解决方案：检查 itemSeparatorComponent 属性是否绑定正确，分割线组件要写返回值（如 ()=><View style={styles.line}/>），且分割线要设置高度；
✘ 坑 4：列表项点击事件没反应 → ✔ 解决方案：用 TouchableOpacity 包裹列表项（不要用 View），onPress 事件要写在 TouchableOpacity 上，且不要给列表项设置 disabled={true}；
✘ 坑 5：列表数据更新了，但页面不刷新 → ✔ 解决方案：数据源要用 useState 声明为响应式数据，修改数据时用 setState 更新，FlatList 会自动刷新；
✘ 坑 6：鸿蒙模拟器列表滑动卡顿 → ✔ 解决方案：部分鸿蒙模拟器的滑动体验一般，用鸿蒙真机测试即可，真机上 FlatList 的滚动流畅度拉满，无卡顿问题。