@bingtang-rn/react-native-big-list for HarmonyOS

本项目基于 react-native-big-list 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 1.6.4 | 1.6.4 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-big-list

使用

import BigList, { BigList as RawBigList } from 'react-native-big-list';

// 基础虚拟化列表
<BigList
  data={items}
  itemHeight={80}
  renderItem={({ item }) => <Row item={item} />}
  headerHeight={80}
  renderHeader={() => <ListHeader />}
  footerHeight={60}
  renderFooter={() => <ListFooter />}
/>;

// 分区列表 + 吸顶 header
<BigList
  sections={sectionsData}
  itemHeight={80}
  renderItem={({ item }) => <Row item={item} />}
  sectionHeaderHeight={56}
  renderSectionHeader={(section) => <SectionHeader section={section} />}
  stickySectionHeadersEnabled
/>;

// 编程式滚动（需原始 class ref，用命名导出 RawBigList）
const ref = useRef<RawBigList<typeof items[0]>>(null);
ref.current?.scrollToIndex({ index: 100, animated: true });

import 时使用原库名 'react-native-big-list'，而非鸿蒙包名（RNOH harmony.alias 自动映射到 @bingtang-rn/react-native-big-list）。

平台差异：

• 本库为纯 JS 虚拟化列表，无原生代码，所有能力通过 RNOH JS 运行时 + RNOH 内置 ScrollView/Animated/RefreshControl/Image 实现。
• 吸顶 Section Header（stickySectionHeadersEnabled）与 nativeOffsetValues 使用 Animated.attachNativeEvent 原生驱动（RNOH 已实现并内部使用），同时保留 JS onScroll 驱动作为安全兜底。

权限要求：

• 无（纯 JS 列表组件，不涉及任何系统权限）。

Manual Link：

• 本库为纯 JS（js_only），无需 C++/ETS 侧 Package 注册。下方 Manual Link 章节为模板脚手架内容，不适用于本库；RNOH harmony.alias 已完成自动链接。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-big-list": "file:../../node_modules/@bingtang-rn/react-native-big-list/harmony/big_list.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-big-list/src/main/cpp" ./big_list)

target_link_libraries(rnoh_app PUBLIC big_list)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "BigListPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<BigListPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { BigListPackage } from '@bingtang-rn/react-native-big-list/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new BigListPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | data + itemHeight + renderItem | 虚拟化长列表渲染 | data: ItemT[], itemHeight: number|function, renderItem: (info) => Element | — | ✅ 完全支持 | | sections + renderSectionHeader/Footer | 分区列表 | sections: ItemT[][], renderSectionHeader/Footer: (section) => Element | — | ✅ 完全支持 | | stickySectionHeadersEnabled | 吸顶 Section Header | boolean | — | ✅ 完全支持 | | nativeOffsetValues | 原生偏移跟踪 | { x?: Animated.Value, y?: Animated.Value } | — | ✅ 完全支持 | | numColumns + columnWrapperStyle | 多列布局 | numColumns: number, columnWrapperStyle: style | — | ✅ 完全支持 | | horizontal | 水平滚动 | boolean | — | ✅ 完全支持 | | placeholder + placeholderImage/Component | 占位渲染 | placeholder: boolean, placeholderImage: any, placeholderComponent: ReactNode | — | ✅ 完全支持 | | onRefresh + refreshing | 下拉刷新 | onRefresh: () => void, refreshing: boolean | — | ✅ 完全支持 | | onEndReached + onEndReachedThreshold | 触底加载 | onEndReached: ({distanceFromEnd}) => void, onEndReachedThreshold: number | — | ✅ 完全支持 | | scrollTo / scrollToTop / scrollToEnd / scrollToIndex / scrollToItem / scrollToOffset / scrollToLocation / scrollToSection / flashScrollIndicators / getNativeScrollRef | 编程式滚动控制（via ref） | 各方法参数见类型声明 | void / ScrollView | ✅ 完全支持 | | getItemOffset / getItem / getItems / isVisible / isEmpty / onViewableItemsChanged | 可见性查询与空状态（via ref） | { index, section? } | number / ItemT / boolean | ✅ 完全支持 | | inverted | 倒序列表 | boolean | — | ✅ 完全支持 | | initialScrollIndex | 初始滚动位置 | number | — | ✅ 完全支持 | | getItemLayout / ListEmptyComponent / ListHeaderComponent / ListFooterComponent / keyExtractor / removeClippedSubviews / refreshing | FlatList 兼容 Props | 各对应 FlatList 同名 prop | — | ✅ 完全支持 |

平台差异

• 无平台差异。本库为纯 JS，所有能力在 HarmonyOS 上与 Android/iOS 行为一致（底层依赖 RNOH ScrollView 映射 ArkUI 滚动容器）。

未实现功能

无。

使用限制

• 大数据量（10,000+ 条）在 RNOH ScrollView 上的滚动流畅度取决于设备性能；建议 itemHeight 用固定数值以走 getItemLayout 短路、开启 removeClippedSubviews 降低内存。
• 含吸顶 Section Header 的列表在吸顶瞬间可能有轻微停顿（RNOH 性能文档已知项），建议限制吸顶组件复杂度。
• scrollToItem 在分区模式下用 JSON.stringify + indexOf 查找（原库既有逻辑），大数据量下性能较差，属原库限制而非适配问题。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无

开源协议

本项目基于 Apache License，详见 LICENSE 文件。