react-native-viewpager

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

项目介绍

@hxa-rn/react-native-viewpager 是 react-native-viewpager 的 React Native 鸿蒙（OpenHarmony）适配包，当前版本 0.2.13-beta.1。

本模块为纯 JS 分页 / 轮播容器，无 TurboModule / Fabric / C++ 原生代码。基于 RN 核心原语（PanResponder、Animated、Dimensions、TouchableOpacity）实现，支持：

• 数据源驱动的多页展示与刷新（ViewPager.DataSource）
• 手势滑动与程序化跳页（goToPage / getCurrentPage / locked）
• 自动播放、循环、自定义间隔
• 默认弹性动画与自定义 animation
• 圆点指示器（颜色、隐藏、自定义、点按跳页）
• initialPage 指定初始页

集成指南

npm install @hxa-rn/react-native-viewpager

ohos/package.json 已配置 harmony.alias = "react-native-viewpager"。业务代码继续按原包名引入：

import ViewPager from 'react-native-viewpager';

peerDependencies：react-native >= 0.72。运行时依赖 prop-types。

纯 JS 模块，无需 HAR / Package 注册或 autolinking。

使用说明

import React, { Component } from 'react';
import { Text, View } from 'react-native';
import ViewPager from 'react-native-viewpager';

const dataSource = new ViewPager.DataSource({
  pageHasChanged: (p1, p2) => p1 !== p2,
});

export default class MyPager extends Component {
  state = {
    dataSource: dataSource.cloneWithPages({
      page1: { title: '第一页' },
      page2: { title: '第二页' },
      page3: { title: '第三页' },
    }),
  };

  render() {
    return (
      <ViewPager
        dataSource={this.state.dataSource}
        renderPage={(data) => (
          <View>
            <Text>{data.title}</Text>
          </View>
        )}
        isLoop
        autoPlay
        onChangePage={(pageNumber) => console.log('当前页:', pageNumber)}
      />
    );
  }
}

接口文档

| API | 描述 | 参数 | 返回值 | |-----|------|------|--------| | dataSource | 页面数据源（必填） | ViewPagerDataSource | — | | renderPage(data, pageID, currentPage) | 页面渲染函数（必填） | (data, pageID, currentPage) => ReactElement | — | | onChangePage(pageNumber) | 页面变更回调 | (pageNumber: number) => void | — | | renderPageIndicator | 自定义指示器 / false 隐藏 | func \| bool | — | | dotColor | 指示器普通点颜色 | string | — | | activeDotColor | 指示器高亮点颜色 | string | — | | isLoop | 无限循环（默认 false） | bool | — | | locked | 禁用触摸滑动（默认 false） | bool | — | | autoPlay | 自动播放（默认 false） | bool | — | | autoScrollInterval | 自动播放间隔（默认 5000ms） | number | — | | animation(animatedValue, toValue, gestureState) | 自定义转场动画 | func | Animated.CompositeAnimation | | initialPage | 初始页索引（0 基） | number | — | | goToPage(pageNumber, animate) | 程序化跳页（实例方法） | (number, boolean?) => void | — | | getCurrentPage() | 获取当前页索引（实例方法） | 无 | number | | ViewPager.DataSource | 数据源构造器 | { pageHasChanged, getPageData? } | ViewPagerDataSource | | cloneWithPages / getPageCount / getPageData | 数据源方法 | 见源码 | 见源码 |

公开 API 均在 src/ 落地。goToPage 在越界时打印错误并返回，不切换页面。

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-viewpager.git
cd react-native-viewpager
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
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。

约束与限制

• 兼容性：Demo compatibleSdkVersion 为 5.0.1(13)；peerDependencies 要求 react-native >= 0.72；Demo 使用 @react-native-oh/react-native-harmony 0.72.139。
• 权限：库本身无额外系统权限。
• 原生代码：无；不支持、也不需要 C++ / ETS Package。
• 渲染窗口：render() 只挂载当前页及相邻 ±1 页，跨多页动画可能露出容器底色。
• 上游状态：原仓库已标注 No more maintenance，鸿蒙侧在本仓库维护。运行态手势手感需在真机确认。

开源license

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

问题反馈渠道

如果在使用过程中有任何问题，欢迎在 AtomGit 提交 Issue，会及时跟进。也可在 GitCode 仓库反馈：

• https://gitcode.com/hxa-rn/react-native-viewpager
• https://gitcode.com/hxa-rn/react-native-viewpager/issues