本项目基于 react-native-ultimate-listview开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-ultimate-listview 是 react-native-ultimate-listview 的鸿蒙（OpenHarmony）适配版本，当前规范版本号为 3.3.0-beta.1。

本库为纯 JS 模块，对外提供 UltimateListView（增强 FlatList）与 UltimateRefreshView（独立下拉刷新 ScrollView）两个组件，支持下拉刷新、自动分页、网格布局与滚动定位等功能。

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | | ------------ | ---------- | ------------ | -------- | | 3.3.0-beta.1 | 3.3.0 | 0.72+ | 否（纯 JS 模块，无自有原生 HAR） |

集成指南

npm install @hxa-rn/react-native-ultimate-listview

本模块为纯 JS（js-only），无自有原生 HAR，无需手动 Link 配置。import 时使用原库名 'react-native-ultimate-listview'，Metro 经包的 harmony.alias 自动重定向。

peerDependencies：react-native（>=0.72）。

displayDate 功能依赖 @react-native-ohos/async-storage（Example 已声明，支持 Autolink）。

使用说明

import React, { useRef } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { UltimateListView } from 'react-native-ultimate-listview';

const PAGE_SIZE = 20;

function generateRows(page: number) {
  return Array.from({ length: PAGE_SIZE }, (_, i) => ({
    id: `item-${(page - 1) * PAGE_SIZE + i + 1}`,
    title: `Item ${(page - 1) * PAGE_SIZE + i + 1}`,
  }));
}

function ListApp() {
  const listRef = useRef<any>(null);

  return (
    <View style={styles.container}>
      <UltimateListView
        ref={listRef}
        onFetch={(page, startFetch) => {
          setTimeout(() => startFetch(generateRows(page), PAGE_SIZE), 1000);
        }}
        refreshableMode="basic"
        autoPagination
        item={(item) => (
          <View style={styles.item}>
            <Text>{item.title}</Text>
          </View>
        )}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  item: { padding: 14, borderBottomWidth: 1, borderBottomColor: '#eee' },
});

export default ListApp;

import React from 'react';
import { Text, StyleSheet } from 'react-native';
import { UltimateRefreshView } from 'react-native-ultimate-listview';

function RefreshApp() {
  return (
    <UltimateRefreshView
      onRefresh={(done) => setTimeout(done, 1500)}
      style={styles.refreshView}
    >
      <Text>下拉刷新内容</Text>
    </UltimateRefreshView>
  );
}

const styles = StyleSheet.create({
  refreshView: { height: 200 },
});

export default RefreshApp;

接口文档

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | UltimateListView | 高性能 FlatList 封装，支持下拉刷新 / 自动分页 / 网格布局 / 滚动定位 | onFetch、refreshableMode、autoPagination、numColumns、item 等 | React 组件 | ✅ 完全支持 | | UltimateListView.refresh() | 触发下拉刷新（等价 onRefresh） | 无 | void | ✅ 完全支持 | | UltimateListView.scrollToOffset() | 滚动到指定偏移量 | { offset, animated } | void | ✅ 完全支持 | | UltimateListView.scrollToIndex() | 滚动到指定索引 | { index, viewPosition, animated } | void | ⚠️ 部分支持（索引未渲染时可能抛异常，需 try-catch） | | UltimateListView.scrollToItem() | 滚动到指定条目 | { item, animated } | void | ✅ 完全支持 | | UltimateListView.scrollToEnd() | 滚动到底部 | { animated } | void | ✅ 完全支持 | | UltimateRefreshView | 独立下拉刷新 ScrollView，内部维护下拉/释放/刷新中状态机 | onRefresh(done)、refreshable、displayDate 等 | React 组件 | ⚠️ 部分支持（负偏移刷新头需真机验证） |

平台差异：

• refreshableMode="advanced" 基于负偏移 scrollTo({y:-height}) 实现，鸿蒙端需真机验证；不支持时可回退为 basic 模式。
• basic 模式 RefreshControl 的 Android 专有透传属性在鸿蒙端按默认刷新指示器渲染。
• displayDate 使用 @react-native-ohos/async-storage 适配包持久化上次更新时间。

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-ultimate-listview.git
cd react-native-ultimate-listview
git checkout br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

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

cd example          # 或 example_auto
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（或 example_auto/harmony）目录
• 等待 Sync 完成

6. 编译并运行 HAP

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

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

约束与限制

兼容性

• 鸿蒙 SDK：API 12+
• 上游 RN SDK：0.72+
• React Native / RNOH：0.72+
• DevEco Studio：5.0+ / 6.0+

权限

• 无额外系统权限

使用限制

• 本模块为纯 JS，依赖 RNOH 基座（FlatList / ScrollView / RefreshControl / Animated）运行。
• scrollToIndex 在目标索引尚未渲染时可能抛异常，调用方须用 try-catch 包裹。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-ultimate-listview

https://gitcode.com/hxa-rn/react-native-ultimate-listview/issues