@bingtang-rn/react-native-picky for HarmonyOS

本项目基于 react-native-picky 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 0.4.0 | 0.72+ | 否 | API17+ |

安装

npm install @bingtang-rn/react-native-picky

使用

import { Picker, PickerColumn, PickerItem } from 'react-native-picky';

// 单列循环选择器
<Picker loop onChange={(e) => console.log(e.value)}>
  <PickerColumn>
    <PickerItem label="Apple" value="apple" />
    <PickerItem label="Banana" value="banana" />
    <PickerItem label="Cherry" value="cherry" />
  </PickerColumn>
</Picker>

// 多列循环选择器
<Picker loop textColor="#333333" textSize={16}>
  <PickerColumn>
    <PickerItem label="A1" value="A1" />
    <PickerItem label="A2" value="A2" />
  </PickerColumn>
  <PickerColumn>
    <PickerItem label="B1" value="B1" />
    <PickerItem label="B2" value="B2" />
  </PickerColumn>
</Picker>

import 时使用原库名 'react-native-picky'，而非鸿蒙包名。

平台差异：

• HarmonyOS 使用 TextPicker 组件实现，hasIndicator 映射到 divider，hasCurtain 映射到上下渐隐效果
• HarmonyOS TextPicker 的渐隐效果不支持自定义颜色，因此 curtainColor 不生效
• HarmonyOS 不支持单项文本颜色（PickerItem.color），仅支持全局 textColor
• HarmonyOS 不支持 numberOfLines，选项文本单行截断

权限要求：

• 无需声明额外权限

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 否 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

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

"dependencies": {
  "@bingtang-rn/react-native-picky": "file:../../node_modules/@bingtang-rn/react-native-picky/harmony/picky.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-picky/src/main/cpp" ./picky)

target_link_libraries(rnoh_app PUBLIC picky)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "PickyPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<PickyPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

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

import { PickyPackage } from '@bingtang-rn/react-native-picky/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | Picker | 滚轮选择器主组件 | loop, hasCurtain, curtainColor, hasIndicator, indicatorColor, indicatorSize, itemSpace, textColor, textSize, numberOfLines, onChange | — | ⚠️ 部分支持 | | PickerColumn | 列定义容器 | width, selectedValue, onChange | — | ⚠️ 部分支持（width 需 API17+） | | PickerItem | 选项定义 | label, value, color, testID | — | ⚠️ 部分支持（color 不支持单项颜色） | | data | 多列选择数据 | PickerDataItem[][] | — | ✅ 完全支持 | | selectedIndexes | 选中项索引 | Int32[] | — | ✅ 完全支持 | | loop | 循环滚动 | boolean | — | ✅ 完全支持 | | hasIndicator | 是否显示指示器 | boolean | — | ✅ 完全支持（通过 divider 实现） | | indicatorColor | 指示器颜色 | Int32 | — | ✅ 完全支持（映射到 divider.color） | | indicatorSize | 指示器线宽 | Float | — | ✅ 完全支持（映射到 divider.strokeWidth） | | hasCurtain | 是否显示遮罩 | boolean | — | ✅ 完全支持（通过 gradientHeight 实现） | | curtainColor | 遮罩颜色 | Int32 | — | ❌ 不支持（TextPicker 渐隐颜色不可配置） | | itemSpace | 选项行间距 | Float | — | ✅ 完全支持（结合 textSize 计算选项完整行高） | | textColor | 全局文本颜色 | Int32 | — | ✅ 完全支持（选中项原色，未选中项渐弱） | | textSize | 全局文本字号 | Float | — | ✅ 完全支持 | | onChange | 选中项变更回调 | DirectEventHandler | {column, index, value} | ✅ 完全支持 | | columnWidths | 列宽 | Float[] | — | ⚠️ 部分支持（需 API17+） | | numberOfLines | 选项文本行数 | Int32 | — | ❌ 不支持（TextPicker 不支持多行） | | PickerItem.color | 单项文本颜色 | ColorValue | — | ❌ 不支持（TextPicker 仅支持全局 textStyle） |

平台差异

• hasCurtain：映射到 TextPicker 的 gradientHeight，关闭时将渐隐高度设置为 0
• curtainColor：TextPicker 的渐隐效果不支持自定义颜色
• hasIndicator / indicatorColor / indicatorSize：映射到 TextPicker 的 divider 属性（颜色、线宽）
• itemSpace：与 textSize 共同计算 TextPicker 的完整选项行高，避免字号大于行高时裁剪文字
• 选中项高亮：选中项使用完整 textColor 和 Medium 字重，待选项、边缘项依次降低透明度

未实现功能

| API | 原因 | |-----|------| | numberOfLines | HarmonyOS TextPicker 不支持多行选项文本，自动单行截断 | | PickerItem.color | HarmonyOS TextPicker 仅支持全局 textStyle，不支持单个选项颜色 | | curtainColor | HarmonyOS TextPicker 的渐隐效果不支持自定义颜色 | | columnWidths | TextPicker 的 columnWidths 属性从 API 18 开始支持，低版本使用等分列宽兜底 |

使用限制

• 原生 Package（ETS + C++）支持 Autolink，应用的 entry/oh-package.json5 需要声明 Picky HAR 依赖
• ArkTS 自定义组件仍需在 Index.ets 的 arkTsComponentNames 中添加 'Picky'，并在 buildCustomRNComponent 中按组件名路由渲染

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

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。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

• PickerItem.color 不支持：HarmonyOS TextPicker 无单项颜色 API
• numberOfLines 不支持：TextPicker 不支持多行选项文本
• curtainColor 不支持：TextPicker 的渐隐效果不支持自定义颜色
• columnWidths 低版本不支持：需 API17+，低版本等分列宽兜底
• ArkTS 自定义组件 Builder 仍需在应用侧注册

开源协议

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