react-native-wheel-picker

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

项目介绍

@hxa-rn/react-native-wheel-picker 是 @gregfrench/react-native-wheel-picker 的鸿蒙适配包，当前版本 1.2.21。

该库提供跨平台曲面滚轮选择器。鸿蒙端为 Fabric 原生组件：JS wrapper 解析 Picker.Item / data，原生侧用 ArkUI TextPicker 实现滚轮、惯性滚动、选中高亮和分割线，并通过 onValueChange 回传选中项的 value。

核心能力：

• 通过 Picker.Item 子项或 data 数组渲染滚轮数据
• selectedValue / selectedIndex 控制选中项
• itemStyle / textColor / textSize / itemSpace 外观定制
• lineColor 纯色分割线，lineGradientColorFrom / lineGradientColorTo 渐变分割线
• enabled 控制是否可滑动
• 选中项变化时触发 onValueChange

集成指南

npm install @hxa-rn/react-native-wheel-picker

工程读取包内 harmony.alias 后，业务代码仍从原包名导入：

import Picker from '@gregfrench/react-native-wheel-picker';

peerDependencies：

• react >= 16.0
• react-native >= 0.72

本包依赖 @react-native-ohos/picker（由 npm 随包安装）。含原生 Fabric 组件；已接入 RNOH Autolink 的工程一般无需手动 Link。若需手动注册：

1. 在 entry/oh-package.json5 添加 HAR 依赖 @hxa-rn/react-native-wheel-picker
2. 在 entry/src/main/cpp/CMakeLists.txt 链接 wheel_picker
3. 在 PackageProvider.cpp 与 RNPackagesFactory.ets 注册 WheelPickerPackage

使用说明

import React, {useState} from 'react';
import {View, Text} from 'react-native';
import Picker from '@gregfrench/react-native-wheel-picker';

function Demo() {
  const [selectedValue, setSelectedValue] = useState(2);

  return (
    <View>
      <Picker
        selectedValue={selectedValue}
        itemStyle={{color: '#FFFFFF', fontSize: 26}}
        itemSpace={20}
        lineColor="#4FC3F7"
        onValueChange={value => setSelectedValue(value)}>
        <Picker.Item label="选项一" value={1} />
        <Picker.Item label="选项二" value={2} />
        <Picker.Item label="选项三" value={3} />
      </Picker>
      <Text>当前选中：{selectedValue}</Text>
    </View>
  );
}

常用写法：

• 子项数据：<Picker.Item label value />。未提供子项时，可传 data={[{value, label}]}。
• 选中：selectedValue 与某项 value 相等时按该值定位；未匹配时使用 selectedIndex，越界则回落到 0。
• 外观：itemStyle.color / itemStyle.fontSize 分别映射为整列 textColor、textSize。
• 分割线：只设 lineColor 为纯色；同时设 lineGradientColorFrom 与 lineGradientColorTo 为渐变。
• 禁用：enabled={false} 时不可滑动。

接口文档

Picker

默认导出。Picker.Item 不直接渲染，由父组件经 React.Children 解析为 {value, label}。

属性 / 回调	类型	默认值	说明
data	{value: number, label: string}[]	—	数据项。存在有效 Picker.Item 子项时优先用子项
enabled	boolean	true	是否可交互；false 时不可滑动
itemSpace	number	20	项间距，鸿蒙侧近似映射为 TextPicker 项高
itemStyle	StyleProp<TextStyle>	{color: "white", fontSize: 26}	提取 color→textColor、fontSize→textSize
lineColor	ColorValue	—	上下分割线纯色，支持 #HEX / rgb() / rgba()
lineGradientColorFrom	ColorValue	—	分割线渐变起始色
lineGradientColorTo	ColorValue	—	分割线渐变结束色
onValueChange	(itemValue) => void	—	选中项变化时回调，参数为该项的 value
selectedIndex	number	0	selectedValue 未匹配到子项时生效；越界回落 0
selectedValue	ItemValue	—	当前选中值；匹配到子项时优先于 selectedIndex
textColor	ColorValue	—	整列文字颜色（也可由 itemStyle.color 派生）
textSize	number	—	整列文字大小（也可由 itemStyle.fontSize 派生）
style	StyleProp<TextStyle>	—	容器样式
testID	string	—	端到端测试标识

鸿蒙端 onValueChange 收到的是原生事件中的 data（即该项 value），不是索引。

Picker.Item

属性	类型	说明
label	string	显示文案
value	ItemValue	选中值，经 onValueChange 回传
color	ColorValue	类型保留，与上游 API 对齐；鸿蒙端不生效
testID	string	测试标识

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/classic-wheel-picker.git
cd classic-wheel-picker
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-wheel-picker@1.2.21，不再使用本地 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。

约束与限制

• 兼容性：鸿蒙 compatibleSdkVersion 为 5.0.1(13)（example 与 example_auto 均为 HarmonyOS）。上游 RN / RNOH 以 peerDependencies 为准：react-native >= 0.72、react >= 16.0；本仓库 Demo 使用 react-native 0.72.5、@react-native-oh/react-native-harmony 0.72.139。
• 权限：插件 OHOS 模块未声明系统权限，无额外系统权限。
• 曲面视觉：基于 ArkUI TextPicker，曲面深度、非居中项缩放与 Android AigeStudio 存在合理差异。
• itemSpace：近似映射为项高，不是 Android 原义的像素间距。
• Picker.Item.color：未实现。TextPicker 仅支持整列 textStyle，不能逐项着色；整列请用 itemStyle.color / textColor。
• selectedIndex：selectedValue 匹配优先；滚动过程中外部回写的旧索引会被忽略，避免滚轮被拉回。

开源license

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

问题反馈渠道

使用过程中如有问题，欢迎在 AtomGit 提交 Issue。也可通过 GitCode 仓库与 Issue 反馈：

• https://gitcode.com/hxa-rn/classic-wheel-picker
• https://gitcode.com/hxa-rn/classic-wheel-picker/issues