react-native-cameraroll

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

项目介绍

@hxa-rn/react-native-cameraroll 是 React Native 相册读取库 react-native-cameraroll 的鸿蒙适配。当前版本 1.1.0-alpha1-beta.1。

核心能力：通过 TurboModule RNCameraRoll.getAssets 从设备相册分页读取图片/视频，按 assetType（image / video / all）过滤，返回 uri、尺寸、文件名、时间戳、拍摄地（若有）及分页游标。实现位于 harmony/cameraroll（ArkTS TurboModule + C++ Package），依赖系统 Media Library Kit（photoAccessHelper），无第三方原生库。

集成指南

npm install @hxa-rn/react-native-cameraroll

在工程 harmony.alias 配置下，业务代码仍按原包名导入：

import RNCameraRoll from 'react-native-cameraroll';

peerDependencies：react-native >= 0.72、react *。

当前版本支持 Autolink。若工程已接入 RNOH Autolink，可跳过手动注册。未开启 Autolink 时，需手动完成 HAR 依赖、CMake 子目录、PackageProvider.cpp 注册 CamerarollPackage，以及 ETS 侧 createRNPackages 返回 new CamerarollPackage(ctx)。

宿主工程 module.json5 建议同步声明库已声明的相册与媒体位置权限（见「约束与限制」）。

使用说明

首次调用 getAssets 时，库内会一次性申请 READ_IMAGEVIDEO 与 MEDIA_LOCATION。拒绝相册读取权限则整页失败；拒绝媒体位置权限时查询仍成功，本页 location 均为 null。

import React from 'react';
import { Button } from 'react-native';
import RNCameraRoll from 'react-native-cameraroll';

export function QueryAlbum() {
  const onPress = async () => {
    try {
      const first = await RNCameraRoll.getAssets({
        assetType: 'image',
        limit: 20,
      });
      console.log(first.assets, first.page_info);
      if (first.page_info.has_next_page) {
        const next = await RNCameraRoll.getAssets({
          assetType: 'image',
          limit: 20,
          start: first.page_info.end_cursor,
        });
        console.log(next.assets);
      }
    } catch (e) {
      console.error(e);
    }
  };
  return <Button title="读取相册" onPress={onPress} />;
}

start 取上一页 page_info.end_cursor。limit 越大，已授权 MEDIA_LOCATION 时本页回填 GPS 的耗时越长，建议按页拉取。

接口文档

公开 API 仅 RNCameraRoll.getAssets。

RNCameraRoll.getAssets

| 项 | 说明 | |----|------| | 调用 | RNCameraRoll.getAssets(params: GetAssetsParams): Promise<GetAssetsResponse> | | 功能 | 按类型分页读取相册资源，按 date_added 倒序（最新在前） | | 注意 | assetType 仅接受 image / video / all；非法值 reject E_INVALID_ASSET_TYPE |

GetAssetsParams

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | assetType | 'image' \| 'video' \| 'all' | 是 | 资源类型过滤 | | limit | number | 是 | 本页返回条数上限 | | start | string \| number | 否 | 分页起点索引，缺省为 0；传入上一页 end_cursor |

GetAssetsResponse

| 字段 | 类型 | 说明 | |------|------|------| | assets | Asset[] | 本页资源 | | page_info | PageInfo | 分页信息 |

Asset

| 字段 | 类型 | 说明 | |------|------|------| | type | 'image' \| 'video' | 资源类型 | | uri | string | 鸿蒙相册 URI，形如 file://media/Photo/... | | filename | string | 显示名（含后缀） | | width | number | 宽度 | | height | number | 高度 | | timestamp | number | Unix 秒，取自 DATE_ADDED | | location | Location \| null | 已授权 MEDIA_LOCATION 且文件含 GPS 时为对象，否则 null |

Location

| 字段 | 类型 | 说明 | |------|------|------| | latitude | number | 纬度 | | longitude | number | 经度 | | altitude | number | 可选；类型声明存在，鸿蒙实现不回填 | | heading | number | 可选；类型声明存在，鸿蒙实现不回填 | | speed | number | 可选；类型声明存在，鸿蒙实现不回填 |

PageInfo

| 字段 | 类型 | 说明 | |------|------|------| | start_cursor | string \| number | 当前页起点索引 | | end_cursor | string \| number | 下一页起点 = start + 实际条数 | | has_next_page | boolean | 是否还有更多资源 |

错误码

| code | 含义 | |------|------| | E_INVALID_ASSET_TYPE | assetType 非法 | | E_PERMISSION_DENIED | 未授予 READ_IMAGEVIDEO | | E_UNABLE_TO_LOAD | 相册查询失败 |

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-cameraroll.git
cd react-native-cameraroll
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。

约束与限制

• 兼容性：示例工程 example / example_auto 的 compatibleSdkVersion 均为 5.0.1(13)。库 peerDependencies 为 react-native >= 0.72、react *；示例使用 react-native 0.72.5、@react-native-oh/react-native-harmony 0.72.140。图片 GPS 读取使用 Image Kit getImageProperties（API 12+）。
• 权限（HAR harmony/cameraroll 的 module.json5 已声明，首次 getAssets 时库内申请）：
  • ohos.permission.READ_IMAGEVIDEO：列出相册图片和视频；拒绝则整页 E_PERMISSION_DENIED。
  • ohos.permission.MEDIA_LOCATION：读取拍摄地；拒绝时查询仍成功，本页 location 均为 null。
• GPS：列表查询后对本页打开文件回填。图片读 EXIF DMS，视频读 AVMetadata。无权限、无定位或单条失败时该条为 null，不 reject 整页。鸿蒙相册无经纬度列，只填 latitude / longitude。
• 分页：start / end_cursor 为索引偏移，与 iOS 一致，不是 Android 的 DATE_TAKEN 数值游标。
• Autolink：含原生，需同时注册 ETS Package 与 C++ Package（CamerarollPackage）。

开源license

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

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-cameraroll

https://gitcode.com/hxa-rn/react-native-cameraroll/issues