@hxa-rn/react-native-photo-browser

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

项目介绍

@hxa-rn/react-native-photo-browser 是 react-native-photo-browser（上游版本 0.7.0）的鸿蒙（OpenHarmony / HarmonyOS，RNOH）适配包，当前版本 0.7.0（与上游版本号一致）。

上游是一个 React Native 图片浏览组件，支持全屏图片浏览、九宫格缩略图浏览、图片翻页、标题说明、图片选择、返回按钮、动作按钮和长按回调。

本包是纯 JS 组件库：不含 ETS / C++ 原生代码，不随包提供 HAR，不参与 Autolink，也不需要 Manual Link。

鸿蒙适配包版本	上游版本	React Native / RNOH	编译 SDK	接入方式
0.7.0	0.7.0	RN >=0.72（基于 0.72.5 + @react-native-oh/react-native-harmony 0.72.143）	compatibleSdkVersion 5.1.0(18)，targetSdkVersion 6.1.1(24)	纯 JS，npm install 后重新生成 JS Bundle 即可，无原生接入步骤

集成指南

1. 安装

在 RN 工程根目录执行：

npm install @hxa-rn/react-native-photo-browser --legacy-peer-deps

务必带 --legacy-peer-deps：运行依赖 @react-native-oh-tpl/react-native-progress 声明了原生 peer @react-native-oh-tpl/react-native-svg（只有它的 Circle / CircleSnail / Pie 需要）。本包只引用纯 JS 的 @react-native-oh-tpl/react-native-progress/Bar，从不引用 svg；不带该参数时 npm 7+ 会自动装入这个原生包，给宿主平添一条无用的 autolinking / HAR 链路。

运行时依赖（随本包自动安装）：

依赖	版本	说明
@react-native-oh-tpl/react-native-progress	~5.0.1-0.0.3	鸿蒙化进度条，仅深引用纯 JS 的 Bar（全屏加载进度）
react-native-iphone-x-helper	^1.2.1	纯 JS；鸿蒙上恒取非刘海屏分支，行为与 Android 一致
prop-types	15.5.10	纯 JS

宿主需自备 react、react-native 与 RNOH（@react-native-oh/react-native-harmony），本包以 peerDependencies 声明前两者。

2. JS 侧导入

业务代码可以继续沿用上游包名：

import PhotoBrowser from 'react-native-photo-browser';

本包 package.json 声明了 "harmony": { "alias": "react-native-photo-browser" }，RNOH 的 createHarmonyMetroConfig 会把上游包名解析到本包，无需改写 import。宿主 metro.config.js 使用 RNOH 模板的标准写法即可：

const {mergeConfig, getDefaultConfig} = require('@react-native/metro-config');
const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');

module.exports = mergeConfig(getDefaultConfig(__dirname), createHarmonyMetroConfig({
  reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
}));

也可以直接使用本包名导入：

import PhotoBrowser from '@hxa-rn/react-native-photo-browser';

本包不随包提供 TypeScript 类型声明。TypeScript 工程在任意被 tsconfig.json 收录的 .d.ts 文件中加一行模块声明，避免 TS7016（按实际使用的导入名二选一或都写）：

declare module 'react-native-photo-browser';
declare module '@hxa-rn/react-native-photo-browser';

3. 鸿蒙原生侧

本包没有原生实现，因此不需要：在 oh-package.json5 / entry/oh-package.json5 中添加依赖、修改 CMakeLists.txt、在 PackageProvider.cpp 或 RNPackagesFactory.ets 中注册 Package。

安装后在 RN 工程根目录重新生成鸿蒙侧 JS Bundle 即可生效：

react-native bundle-harmony --dev false

默认写入 ./harmony/entry/src/main/resources/rawfile/bundle.harmony.js，本包的图片资源写入同级 assets/ 目录；鸿蒙工程不在 ./harmony 时，用 --bundle-output / --assets-dest 指定。随后用 DevEco Studio 编译运行宿主工程。

使用说明

基础用法

import React from 'react';
import PhotoBrowser from 'react-native-photo-browser';

const mediaList = [
  {
    photo: 'https://example.com/photo-1.jpg',
    thumb: 'https://example.com/thumb-1.jpg',
    caption: 'Photo 1',
    selected: false,
  },
  {
    photo: 'https://example.com/photo-2.jpg',
    thumb: 'https://example.com/thumb-2.jpg',
    caption: 'Photo 2',
    selected: true,
  },
];

export default function Gallery() {
  return (
    <PhotoBrowser
      mediaList={mediaList}
      initialIndex={0}
      enableGrid
      startOnGrid={false}
      displaySelectionButtons
      displayNavArrows
      displayActionButton
      alwaysDisplayStatusBar
      itemPerRow={3}
      onSelectionChanged={(media, index, isSelected) => {
        console.log('selection', media, index, isSelected);
      }}
      onActionButton={(media, index) => {
        console.log('action', media, index);
      }}
      onBack={() => {
        console.log('back');
      }}
    />
  );
}

常用场景

场景	配置方式
默认全屏浏览	传入 mediaList，保持 startOnGrid={false}
默认九宫格浏览	传入 startOnGrid={true}
显示选择按钮	传入 displaySelectionButtons={true} 并监听 onSelectionChanged
显示左右导航箭头	传入 displayNavArrows={true}
显示动作按钮	传入 displayActionButton={true} 并监听 onActionButton
自定义网格列数	传入 itemPerRow
控件常显	传入 alwaysShowControls={true}

接口文档

PhotoBrowser 属性

属性	类型	默认值	说明	HarmonyOS 支持
mediaList	Array<Media>（必填）	[]	图片媒体列表	是
style	ViewStyle	无	容器样式	是
initialIndex	number	0	全屏浏览初始图片索引	是
square	boolean	false	九宫格缩略图是否使用正方形	是
gridOffset	number	0	从九宫格可用宽度中扣除的偏移量	是
itemPerRow	number	3	九宫格每行缩略图数量	是
alwaysShowControls	boolean	false	顶栏、底栏和控制按钮是否常显	是
displayActionButton	boolean	false	是否显示动作按钮	是
displayNavArrows	boolean	false	是否显示左右导航箭头	是
alwaysDisplayStatusBar	boolean	false	控件隐藏时是否保持系统状态栏可见	是（见约束与限制）
enableGrid	boolean	true	是否启用九宫格入口	是
startOnGrid	boolean	false	是否默认从九宫格视图启动	是
displaySelectionButtons	boolean	false	是否显示图片选择按钮	是
displayTopBar	boolean	true	是否显示顶部栏	是
useCircleProgress	boolean	false	请求使用圆形加载进度	部分：降级为条形进度
delayPhotoLongPress	number	1000	图片长按触发时长，单位 ms	是
customBottomBarButton	React.ReactElement	无	在底栏动作按钮左侧插入的自定义按钮	是
customTitle	(index, total) => string	无	全屏模式的标题，index 从 1 起；未传入时为 "<index> of <total>"	是
onSelectionChanged	(media, index, isSelected) => void	空函数	图片选择状态变化回调	是
onActionButton	(media, index) => void	无	动作按钮点击回调	是
onBack	() => void	无	返回按钮点击回调（实际会收到按压事件，可忽略）；未传入时不显示返回按钮	是
onPhotoLongPress	(media, index) => void	空函数	图片长按回调	是

另有上游代码支持、但上游文档未列出的 topBarComponent / bottomBarComponent（替换顶栏 / 底栏组件），行为与上游一致。

Media

字段	类型	是否必填	说明
photo	string / 图片资源	是	大图，远程 URI 或 require() 得到的 RN 图片资源
thumb	string / 图片资源	否	缩略图，缺省时回落使用 photo
caption	string	否	图片说明文字
selected	boolean	否	初始选中状态
id	string / number	否	媒体唯一标识，列表 key 优先使用它

回调说明

回调	触发时机	参数
onSelectionChanged	用户点击选择按钮后	当前媒体对象、索引、选中状态
onActionButton	用户点击动作按钮后	当前媒体对象、索引
onBack	用户点击返回按钮后	无
onPhotoLongPress	用户长按当前图片后	当前媒体对象、索引

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>= 20（示例工程 engines 要求）；DevEco Sync 时 preInstall 钩子也要用 PATH 中的 Node.js 20+，新装 Node.js 后需重启 DevEco Studio
DevEco Studio	6.1.1（本版本验证所用）
HarmonyOS SDK	API 18+（example/harmony 的 compatibleSdkVersion 为 5.1.0(18)）
路径	Windows 下仓库根目录的完整路径不超过 40 个字符，否则原生构建的中间文件路径会超过系统上限

运行步骤

1. 克隆仓库

git clone -b br_rnoh0.72 https://gitcode.com/hxa-rn/react-native-photo-browser.git
cd react-native-photo-browser

Windows 下可在克隆时指定短目录名，例如 git clone -b br_rnoh0.72 https://gitcode.com/hxa-rn/react-native-photo-browser.git C:\rpb。

2. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

Example 从 npm 公仓安装 @hxa-rn/react-native-photo-browser@0.7.1，不需要在仓根执行 npm pack。

3. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

4. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio，选择 example/harmony 目录
• 首次构建请在 File → Project Structure → Signing Configs 勾选 Automatically generate signature，Apply 后 Sync
• 等待 Sync 完成

5. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备。

example_auto（自动化用例工程）步骤相同，把 example 换成 example_auto 即可，两者的依赖与构建输出相互独立。

注意：本包为纯 JS，Example 无原生接入步骤，Metro alias 已预置。编 HAP 前必须先执行 npm run dev；改过 JS 后重新执行再运行。两个示例的应用包名均为 com.example.react_native_photo_browser；示例图片来自网络（picsum.photos），设备需可联网。

约束与限制

兼容性

• React 18.2.0，React Native 0.72.5，RNOH @react-native-oh/react-native-harmony 0.72.143
• HarmonyOS SDK：compatibleSdkVersion 5.1.0(18)，targetSdkVersion 6.1.1(24)

以上为本版本编译验证所用的环境（DevEco Studio 6.1.1），不代表其他 RNOH / SDK 版本不可用，但未经验证。

验证状态

• 0.7.0：版本号改为与上游版本一致，代码与 1.0.1 相同。版本号低于此前发布的 1.0.x，^1.0.0 之类的范围不会解析到本版本，请按精确版本安装。发布前以候选包为依赖，example 与 example_auto 在上述环境中 assembleHap 编译通过；未做真机验证。
• 1.0.1：全屏模式右上角选择按钮的位置恢复为上游取值（fullScreenSelectionIcon 的 top 由 112 改回 142；1.0.0 曾为适配示例安全区改小），其余代码与 1.0.0 相同。发布前以候选包为依赖，example 与 example_auto 在上述环境中 assembleHap 编译通过；未做真机验证。
• 1.0.0：在 0.0.1-beta 基础上修复「从九宫格点缩略图回到全屏时，大图偶发以错误尺寸显示（近乎不可见），翻页后恢复」的问题（全屏列表随视口变化重渲染），并让全屏标题在首帧即正确显示。本版本发布前未单独做编译或真机验证。
• 0.0.1-beta：以源码仓库的 example 与 example_auto 两个示例工程为宿主，从 npm 安装本包，在上述环境中 assembleHap 编译通过；真机（HarmonyOS API 26）冒烟通过了全屏浏览、翻页、九宫格与返回，并发现了上述已在 1.0.0 修复的问题。
• 尚未完成：功能黑盒用例集（28 例）尚未在 1.0.0、1.0.1、0.7.0 上重跑。

与 Android / iOS 的行为差异

#	差异	说明	影响
1	全屏加载进度恒为条形	上游 Android 显示系统转圈（ActivityIndicator），iOS 可用 useCircleProgress 切到圆环；圆环依赖原生 svg，本包不引入，鸿蒙侧恒为条形进度	视觉差异，功能不受影响
2	加载进度随框架实现而异	RNOH 0.72.143 C-API 支持 Image.onProgress 的字节进度；无此回调的实现下从加载态直接完成	大图按真实回调更新进度，缓存命中可能直接完成；缩略图不展示增量进度
3	状态栏作用于整个窗口	鸿蒙的状态栏设置作用于整个应用窗口，translucent 为空操作；本组件默认在切换控件显隐时同步隐藏 / 显示状态栏	建议传 alwaysDisplayStatusBar={true}；若宿主其他页面对状态栏样式敏感，离开 PhotoBrowser 后自行重设
4	返回按钮无文字	与 Android 一致只显示箭头图标	视觉差异
5	EXIF 旋转元数据	RNOH 的 orientation=auto 依赖 ArkUI NODE_IMAGE_ORIENTATION，仅 API 21+ 支持；更低 API 的设备上带旋转信息的图片按原始方向显示	建议设备 API 21+，或业务侧预先旋正图片

相对上游的主要库内改动

• FullScreenContainer：补 componentWillUnmount，移除 didUpdateDimensions 监听并清理懒加载重试定时器（上游监听器从不移除，会对已卸载组件 forceUpdate）
• FullScreenContainer：越界的 initialIndex 钳制到有效范围（上游首帧会因读取不存在的图片而崩溃）
• index.js：字符串 ref 改为 React.createRef()（React 18 已废弃字符串 ref）
• index.js / bar/BarContainer.js：Animated.timing 补 useNativeDriver
• propTypes.js：以 stylePropType 替代 ViewPropTypes.style（RNOH 的 react-native-harmony 导出表无 ViewPropTypes，0.72.101 核实；直接引用会导致整库加载即崩）
• GridContainer：numColumns 跟随 itemPerRow（上游写死 3 列）

其他约束

• 本库不主动申请系统权限；远程图片访问（网络）、相册读取等权限由业务应用按自身场景声明。
• 本库不内置系统分享、复制或保存到相册能力，业务侧可在 onActionButton 中自行实现。
• 九宫格重排依赖应用窗口实际尺寸变化；应用未开启转屏时不会触发布局重排。

开源license

本项目基于 MIT License 开源，与上游 react-native-photo-browser 一致，详见包内 LICENSE。

问题反馈渠道

使用过程中发现问题，请在 GitCode Issues 提交，并附上：

• 问题现象和复现步骤
• 设备型号、系统版本和 API 档位
• React Native、RNOH 与本库版本
• 最小可复现代码或截图、日志