stream-io_flat-list-mvcp for HarmonyOS

本项目基于 @stream-io/flat-list-mvcp 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。

简介

stream-io_flat-list-mvcp 为 React Native HarmonyOS 应用提供带 maintainVisibleContentPosition 配置能力的列表组件封装。当前 HarmonyOS 原生层负责 MVCP 配置的句柄分配、状态存储和清理。

导出组件：

• FlatList - 基于 React Native FlatList 的封装，传入 maintainVisibleContentPosition 时自动管理 MVCP 句柄
• ScrollView - 基于 React Native ScrollView 的封装，传入 maintainVisibleContentPosition 时自动管理 MVCP 句柄

导出 API：

• useMvcpTuner - Hook，用于为自定义 FlatList 封装管理 MVCP 启用和清理生命周期
• MvcpScrollViewManager - TurboModule，用于直接启用或禁用指定滚动节点的 MVCP 句柄
• maintainVisibleContentPositionPropType - maintainVisibleContentPosition 配置的 TypeScript 类型

| 版本 | 支持 RN 版本 | Autolink | License | |------|-------------|----------|---------| | 1.0.0 | 0.72+ | 是 | MIT |

下载安装

npm install stream-io_flat-list-mvcp

Link 配置

当前版本支持 Autolink，如工程已接入 RNOH Autolink，无需手动配置。

1. 引入原生端依赖

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

"dependencies": {
  "stream-io_flat-list-mvcp": "file:../../node_modules/stream-io_flat-list-mvcp/harmony/flat_list_mvcp.har"
}

执行 ohpm install。

2. 注册 Package（ETS 侧）

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

import FlatListMvcpPackage from 'stream-io_flat-list-mvcp';

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

约束与限制

• RNOH: 0.72+
• HarmonyOS SDK: API 12+
• DevEco Studio: 5.0+
• Node.js: >= 18

平台限制：

HarmonyOS 缺少 Android 的 UIManagerModuleListener 全局布局监听机制。依据适配产物与设备验证记录，当前 TurboModule 仅实现句柄分配、配置存储和句柄清理；设备测试验证了模块加载及启用、禁用调用，未验证所有内容增删场景下与 Android 完全一致的滚动位置维持效果。

目录说明

ohos/
├── src/                              # TypeScript 源码
│   ├── index.ts                      # 主入口，导出组件和 API
│   ├── FlatList.harmony.tsx          # FlatList 鸿蒙适配
│   ├── ScrollView.harmony.tsx        # ScrollView 鸿蒙适配
│   ├── useMvcpTuner.ts               # MVCP Hook
│   └── specs/v1/                     # TurboModule 规范
├── dist/                             # 构建输出，发布 npm 前自动生成
├── harmony/flat_list_mvcp/           # 原生模块
│   ├── index.ets                     # 原生入口
│   └── src/main/
│       ├── ets/                      # ETS 实现
│       └── cpp/                      # C++ 实现
├── example/                          # 示例工程及本地 tgz 依赖
└── package.json

示例工程

快速开始

# 1. 克隆仓库
git clone https://gitcode.com/CPF-RN/stream-io_flat-list-mvcp.git

# 2. 进入仓库的 example 目录
cd stream-io_flat-list-mvcp/example

# 3. 安装依赖
npm run setup

# 4. 生成鸿蒙 JS bundle
npm run dev

# 5. 启动服务
npm start

可用脚本

| 命令 | 说明 | |------|------| | npm run setup | 安装依赖（首次克隆后使用） | | npm run dev | 生成鸿蒙 JS bundle（TypeScript 检查 + bundle-harmony） | | npm start | 启动 Metro 服务 | | npm run i | 重新打包并安装依赖（修改库代码后使用） | | npm run pack:pkg | 仅打包 tgz（输出到 example/） | | npm run tsc | TypeScript 类型检查 |

开发流程

# 首次运行
npm run setup
npm run dev
npm start

# 修改代码后
npm run dev
npm start

# 修改库代码后
npm run i
npm run dev
npm start

使用说明

import { FlatList, ScrollView } from 'stream-io_flat-list-mvcp';

// FlatList 使用
<FlatList
  data={messages}
  renderItem={renderMessage}
  maintainVisibleContentPosition={{
    autoscrollToTopThreshold: 10,
    minIndexForVisible: 1,
  }}
  inverted
/>

// ScrollView 使用
<ScrollView
  maintainVisibleContentPosition={{
    autoscrollToTopThreshold: 10,
    minIndexForVisible: 1,
  }}
>
  {children}
</ScrollView>

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | autoscrollToTopThreshold | number \| null | 否 | 传给 MVCP 管理器的自动滚动阈值。当前组件封装会将未提供、null 或 0 转为禁用阈值。 | | minIndexForVisible | number | 是 | 传给 MVCP 管理器的最小可见索引。当前组件封装会将 0 转为 1。 |

如需禁用 MVCP，请移除 maintainVisibleContentPosition 属性或将其设为 undefined。插件导出的 FlatList 和 ScrollView 已自动管理句柄，常规使用无需直接调用 MvcpScrollViewManager。

接口说明

| API | 说明 | 参数 | 返回值 | |-----|------|------|--------| | FlatList | 自动管理 MVCP 句柄的 React Native FlatList 封装 | FlatListProps<T> | React 组件 | | ScrollView | 自动管理 MVCP 句柄的 React Native ScrollView 封装 | ScrollViewProps | React 组件 | | useMvcpTuner | 为自定义 FlatList 封装管理 MVCP 生命周期 | (flRef: MutableRefObject<FlatList \| undefined>, refReady: boolean, mvcp?: maintainVisibleContentPositionPropType, extraData?: any) | void | | MvcpScrollViewManager.enableMaintainVisibleContentPosition | 为指定滚动节点分配句柄并存储 MVCP 配置 | (viewTag: number, autoscrollToTopThreshold: number, minIndexForVisible: number) | Promise<number> | | MvcpScrollViewManager.disableMaintainVisibleContentPosition | 根据句柄清理对应 MVCP 配置 | (handle: number) | Promise<null> | | maintainVisibleContentPositionPropType | MVCP 配置类型 | { autoscrollToTopThreshold?: number \| null; minIndexForVisible: number } | TypeScript 类型 |

enableMaintainVisibleContentPosition 返回的句柄必须传给 disableMaintainVisibleContentPosition 完成清理。disableMaintainVisibleContentPosition 的返回值仅表示异步调用完成，业务代码不应依赖其值。

贡献代码

1. Fork 本仓库
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

开源协议

本项目基于 MIT License。