react-native-wheel-picker

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

项目介绍

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

该库提供跨平台曲面滚轮选择器。鸿蒙端为 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 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。

约束与限制

• 兼容性：鸿蒙 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