相机胶卷/相册访问模块，用于读写设备媒体资源

react-native-cameraroll

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

项目介绍

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

核心能力：通过 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 main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-cameraroll@1.1.3，不再使用本地 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）。