@hxa-rn/stream-io_flat-list-mvcp

本项目基于 @stream-io/flat-list-mvcp 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

本项目基于 @stream-io/flat-list-mvcp 适配，面向 React Native for OpenHarmony（RNOH）提供 FlatList 与 ScrollView 的 maintainVisibleContentPosition 接口兼容能力。适用于聊天消息列表、双向无限滚动等内容变化时需要保持可见位置的场景。

• FlatList：React Native FlatList 的鸿蒙封装，转发 FlatListProps 并处理 maintainVisibleContentPosition。
• ScrollView：React Native ScrollView 的鸿蒙封装，转发 ScrollViewProps 并处理 maintainVisibleContentPosition。
• useMvcpTuner：根据列表 ref、配置与额外数据管理位置维持句柄的 Hook。
• MvcpScrollViewManager：MvcpScrollViewManager TurboModule 的 JS 侧实例。
• maintainVisibleContentPositionPropType：位置维持配置的 TypeScript 类型。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/stream-io_flat-list-mvcp

该包声明以下 peer dependency，宿主工程需自行提供：

• react
• react-native（>=0.72）

Autolinking

本库已配置 HarmonyOS autolinking，安装依赖后由宿主工程自动接入、无需手动注册。

导入

import {
  FlatList,
  ScrollView,
  MvcpScrollViewManager,
  useMvcpTuner,
} from '@hxa-rn/stream-io_flat-list-mvcp';
import type { maintainVisibleContentPositionPropType } from '@hxa-rn/stream-io_flat-list-mvcp';

使用说明

基础用法

import React from 'react';
import { Text } from 'react-native';
import { FlatList } from '@hxa-rn/stream-io_flat-list-mvcp';

type Message = {
  id: string;
  text: string;
};

const messages: Message[] = [
  { id: '1', text: '历史消息 1' },
  { id: '2', text: '历史消息 2' },
];

<FlatList<Message>
  data={messages}
  renderItem={({ item }) => <Text>{item.text}</Text>}
  keyExtractor={(item) => item.id}
  inverted
  maintainVisibleContentPosition={{
    autoscrollToTopThreshold: 100,
    minIndexForVisible: 1,
  }}
/>;

maintainVisibleContentPosition 为可选属性，未提供时不启用位置维持；其中 autoscrollToTopThreshold 为自动滚动到顶部的阈值，minIndexForVisible 为用于位置维持处理的最小可见索引。inverted 用于倒序列表（如聊天消息）。

ScrollView

import React from 'react';
import { ScrollView } from '@hxa-rn/stream-io_flat-list-mvcp';

<ScrollView
  maintainVisibleContentPosition={{
    autoscrollToTopThreshold: 100,
    minIndexForVisible: 1,
  }}
>
  {children}
</ScrollView>;

ScrollView 与 FlatList 的 maintainVisibleContentPosition 配置方式一致。需要自行管理列表 ref 或在数据变化时重新触发处理时，可使用 useMvcpTuner Hook，详见接口文档。

接口文档

以下 API 依据 src/index.ts、src/FlatList.harmony.tsx、src/ScrollView.harmony.tsx、src/useMvcpTuner.ts 及相关类型定义整理。

FlatList

鸿蒙版 FlatList 封装，转发 React Native FlatList 属性，并处理 maintainVisibleContentPosition 属性。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | maintainVisibleContentPosition | maintainVisibleContentPositionPropType | 未声明 | 位置维持配置；未提供时不启用位置维持。 |

ScrollView

鸿蒙版 ScrollView 封装，转发 React Native ScrollView 属性，并处理 maintainVisibleContentPosition 属性。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | maintainVisibleContentPosition | maintainVisibleContentPositionPropType | 未声明 | 位置维持配置；未提供时不启用位置维持。 |

maintainVisibleContentPositionPropType

位置维持配置类型，定义于 src/useMvcpTuner.ts。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | autoscrollToTopThreshold | number \| null | 未声明 | 可选的自动滚动到顶部阈值；未提供或为 null 时由实现使用禁用阈值。 | | minIndexForVisible | number | 未声明 | 用于位置维持处理的最小可见索引。 |

useMvcpTuner

根据列表 ref、配置与额外数据管理位置维持句柄的 Hook。

useMvcpTuner(
  flRef: MutableRefObject<FlatList | undefined>,
  refReady: boolean,
  mvcp?: maintainVisibleContentPositionPropType,
  extraData?: any
): void;

| 参数 | 类型 | 说明 | | --- | --- | --- | | flRef | MutableRefObject<FlatList \| undefined> | 指向 FlatList 实例的 ref。 | | refReady | boolean | 表示列表 ref 是否已经可用。 | | mvcp | maintainVisibleContentPositionPropType | 位置维持配置；未提供时不启用。 | | extraData | any | 用于触发重新处理的额外依赖值。 |

MvcpScrollViewManager

MvcpScrollViewManager TurboModule 的 JS 侧实例，提供 enableMaintainVisibleContentPosition 与 disableMaintainVisibleContentPosition 方法。

enableMaintainVisibleContentPosition(
  viewTag: number,
  autoscrollToTopThreshold: number,
  minIndexForVisible: number
): Promise<number>;

disableMaintainVisibleContentPosition(handle: number): Promise<null>;

• enableMaintainVisibleContentPosition：为目标 ScrollView 启用位置维持，返回用于后续禁用的唯一句柄。
• disableMaintainVisibleContentPosition：按句柄清理位置维持状态；对不存在或已清理的句柄按幂等方式完成。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | | :-- | --- | | Node.js | >=20 | | React Native for OpenHarmony | 0.72.139 | | HarmonyOS SDK | API 21+ |

运行步骤

1. 获取开发分支源码：

git clone -b stream-io_flat-list-mvcp_dev https://gitcode.com/hxa-rn/stream-io_flat-list-mvcp.git

2. 进入仓库根目录：

cd stream-io_flat-list-mvcp

3. 安装根目录依赖：

npm i

4. 生成供示例工程安装的本地安装包：

npm pack

5. 进入 example 目录：

cd example

6. 安装示例工程依赖：

npm i

7. 生成 React Native JavaScript Bundle：

npm run dev

8. 使用 DevEco Studio 打开 example/harmony 工程，同步依赖并完成签名配置后构建运行。

约束与限制

兼容性

| 依赖 | 要求 | | --- | --- | | React Native for OpenHarmony | >=0.72 | | HarmonyOS SDK | API 21+ | | Example 工程 compatibleSdkVersion | 6.0.1(21) | | Example 工程 targetSdkVersion | 6.1.1(24) | | Node.js | >=18 |

使用限制

• 鸿蒙 TurboModule 当前主要提供启用/禁用句柄管理与跨端 API 兼容，不提供 Android UIManagerModuleListener 的全局布局更新监听等价物。
• onScrollFrameBegin 仅在滚动过程中触发，不会覆盖 Android 侧由任意布局变化触发的全部更新时机。
• Scroller.getItemRect(index) 仅适用于可见子组件，不可见子组件的位置无法按 Android getChildAt 的方式获取。
• 内容插入、删除或批量更新时，实际可见位置维持效果可能与 Android 不同，生产使用前应在目标设备与业务数据更新场景中验证。
• 当前版本不应宣传为完整实现 Android 端的自动位置补偿；如业务依赖该能力，应结合列表自身的 onLayout、数据变化监听与滚动逻辑补充验证与处理。
• 原始库的横向列表不在当前适配验证范围内。

系统权限

本库不依赖额外的 HarmonyOS 系统权限。

开源 License

本项目采用 MIT，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。