@bingtang-rn/react-native-customized-image-picker for HarmonyOS

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

版本对应关系

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

安装

npm install @bingtang-rn/react-native-customized-image-picker

使用

import ImageCropPicker from 'react-native-customized-image-picker';

// ① 从图库选择图片（单选 + 裁剪 + 压缩）
const images = await ImageCropPicker.openPicker({
  cropping: true,
  CropW: 300,
  CropH: 300,
  compressQuality: 80,
  multiple: false,
});

// ② 从图库多选（图+视频混合，附 base64）
const mixed = await ImageCropPicker.openPicker({
  multiple: true,
  maxSize: 5,
  isSelectBoth: true,
  includeBase64: false,
});

// ③ 拍照
const photo = await ImageCropPicker.openCamera({ isVideo: false });

// ④ 录像（限制 30 秒）
const video = await ImageCropPicker.openCamera({
  isVideo: true,
  videoMaximumDuration: 30,
});

// ⑤ 清理本模块产生的临时文件
await ImageCropPicker.clean();

import 时使用原库名 'react-native-customized-image-picker'，RNOH alias 会自动重定向到鸿蒙包 @bingtang-rn/react-native-customized-image-picker，业务代码无需修改。

平台差异：

• HarmonyOS 图库走系统 PhotoViewPicker，无法定制 UI（title/spanCount/openCameraOnStart 等选项不生效，已忽略）。
• HarmonyOS 无系统级裁剪 UI，cropping 降级为按 CropW/CropH 或 aspectRatioX/Y 自动 ROI 居中裁剪（无交互）；showCropCircle 降级为按 circleCropRadius 直径做正方形 ROI（不渲染圆形遮罩）。
• imageLoader（PICASSO/GLIDE/FRESCO/UNIVERSAL）鸿蒙端统一用 Image 组件 + PixelMap，忽略。
• 视频压缩：原库 Compression.compressVideo 即为 TODO 直接 resolve 原路径，鸿蒙端同样不实现转码压缩。
• 视频元数据（width/height/duration）通过 AVMetadataExtractor 提取，duration 已转换为秒（对齐 iOS PHAsset.duration）。
• 取消选择/拍摄统一 reject {code:'cancel', message:'cancel'}，与原库 Android/iOS 一致。

权限要求：

• PhotoViewPicker 与 cameraPicker.pick 均为系统选择器应用，调用方应用无需声明 ohos.permission.CAMERA 或存储权限。
• 文件读写/清理均在应用沙箱 cacheDir 内，无需额外权限。

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-customized-image-picker": "file:../../node_modules/@bingtang-rn/react-native-customized-image-picker/harmony/customized_image_picker.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-customized-image-picker/src/main/cpp" ./customized_image_picker)

target_link_libraries(rnoh_app PUBLIC customized_image_picker)

4. 注册 Package（C++ 侧）

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

#include "CustomizedImagePickerPackage.h"

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

5. 注册 Package（ETS 侧）

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

import { CustomizedImagePickerPackage } from '@bingtang-rn/react-native-customized-image-picker/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | openPicker | 拉起图库选择图片/视频，支持单/多选、裁剪、压缩、Base64 | Options | Promise<Image[]> | ✅ 完全支持 | | openCamera | 拉起相机拍照/录像，支持裁剪（仅图片） | Options | Promise<Image[]> | ✅ 完全支持 | | clean | 清理本模块在沙箱 cacheDir 产生的临时文件目录 | 无 | Promise | ✅ 完全支持 |

Options 字段支持矩阵

| Option | 描述 | HarmonyOS 支持 | |--------|------|----------------| | multiple / maxSize | 多选与上限 | ✅ 完全支持（映射 PhotoSelectOptions.maxSelectNumber） | | isVideo / isSelectBoth | 媒体模式 | ✅ 完全支持（映射 PhotoViewMIMETypes） | | cropping / CropW / CropH / aspectRatioX / aspectRatioY | 裁剪 | ⚠️ 部分支持（无交互 UI，按参数自动 ROI 居中裁剪） | | showCropCircle / circleCropRadius | 圆形裁剪 | ⚠️ 部分支持（降级为按直径正方形 ROI，无圆形遮罩） | | compressQuality / minCompressSize / width / height | 压缩 | ✅ 完全支持（ImagePacker.packToFile + DecodingOptions.desiredSize） | | includeBase64 | Base64 数据 | ✅ 完全支持（util.Base64Helper） | | videoMaximumDuration | 录像最大时长 | ✅ 完全支持（映射 PickerProfile.videoDuration） | | isPlayGif / isGif | GIF 支持 | ✅ 完全支持（HarmonyOS Image 组件原生支持 GIF 动图） | | title / spanCount / openCameraOnStart / returnAfterShot / multipleShot / isHidePreview / isHideVideoPreview / isCamera | 图库 UI 定制 | ❌ 不支持（系统 PhotoViewPicker 不暴露这些 UI 选项） | | imageLoader | 图片加载库选择 | ❌ 不支持（鸿蒙统一用 Image 组件 + PixelMap） | | videoQuality | 视频质量档位 | ❌ 不支持（cameraPicker 不暴露质量档位字段） | | isRecordSelected / allowPickingOriginalPhoto / sortAscendingByModificationDate / showSelectedIndex / allowPickingMultipleVideo / allowPickingVideo / allowPickingImage / allowTakeVideo | iOS TZImagePickerController 专属 | ❌ 不支持（iOS 专属，鸿蒙忽略） |

平台差异

• 图库 UI：HarmonyOS 走系统 PhotoViewPicker，仅支持 MIMEType + maxSelectNumber，原库的 title/spanCount/openCameraOnStart/returnAfterShot/multipleShot/isHidePreview/isHideVideoPreview/isCamera 等 UI 细粒度选项无对应语义，已忽略不生效。
• 裁剪：HarmonyOS 无系统级裁剪 UI，cropping/CropW/CropH/aspectRatioX/aspectRatioY 降级为按参数自动 ROI 居中裁剪（无交互）；showCropCircle/circleCropRadius 降级为按直径做正方形 ROI（不渲染圆形遮罩）。
• 视频压缩：原库 Android Compression.compressVideo 为 TODO（直接 resolve 原路径），鸿蒙端保持一致行为，不实现转码压缩。
• 视频元数据：width/height/duration 通过 AVMetadataExtractor 提取，duration 单位为秒（对齐 iOS PHAsset.duration）。
• 取消语义：用户取消选择/拍摄统一 reject {code:'cancel', message:'cancel'}，与原库 Android/iOS 一致。

未实现/降级功能

| 项 | 原因 | |-----|------| | 图库 UI 细粒度定制（title/spanCount/openCameraOnStart 等） | 系统 PhotoViewPicker 不暴露这些 UI 选项 | | 交互式裁剪页（uCrop/TZImageCropManager） | HarmonyOS 无系统裁剪 UI，自动 ROI 为最接近替代 | | 圆形裁剪遮罩渲染 | 无系统圆形遮罩 API，降级为正方形 ROI | | imageLoader 选项 | 鸿蒙统一用 Image 组件 + PixelMap，无对应加载库概念 | | videoQuality 视频质量档位 | cameraPicker 不暴露质量档位字段 | | 视频压缩转码 | 原库未实现（TODO），保持对等 | | iOS 专属选项（isRecordSelected/allowPickingXxx 等） | iOS TZImagePickerController 专属，鸿蒙忽略 |

使用限制

• 相机/图库均为系统选择器应用，调用方应用无需声明 ohos.permission.CAMERA 或存储权限。
• 文件读写/清理在应用沙箱 cacheDir 内，无额外权限。
• 返回 path 为沙箱 cacheDir/ImageCropPicker/ 下临时文件绝对路径，需用 file:// 前缀作为 Image 组件 source。
• 设备需支持 SystemCapability.Multimedia.Camera.Core（相机）与 SystemCapability.FileManagement.PhotoAccessHelper.Core（图库）。

快速验证（运行 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+

遗留问题

无（或列出已知问题）

开源协议

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