1. 项目背景与核心挑战

在鸿蒙生态中集成React Native能力，是当前跨平台开发领域的重要技术方向。react-native-camera-roll作为React Native生态中管理设备相册的核心组件，其鸿蒙化改造涉及到底层文件系统、权限模型和媒体库接口的深度适配。不同于Android/iOS平台，鸿蒙系统的媒体存储服务采用全新的分布式设计理念，这给传统RN模块的移植带来了三个关键挑战：

1. 媒体存储API差异 ：鸿蒙的媒体库管理接口（@ohos.file.photoAccessHelper）与Android的MediaStore在数据模型和操作方式上存在显著区别
2. 权限体系重构 ：鸿蒙的权限申请机制和范围定义（如ohos.permission.READ_IMAGEVIDEO）需要重新适配
3. 异步通信机制 ：鸿蒙ArkUI的Promise化接口与RN原有的Callback模式需要桥接层转换

提示：鸿蒙3.0之后新增的媒体文件访问安全沙箱机制，要求所有相册操作必须通过photoAccessHelper提供的安全路径进行

2. 环境准备与依赖配置

2.1 开发环境基线要求

• DevEco Studio 3.1+（需开启ArkCompiler支持）
• React Native 0.72+（建议使用0.72.4版本验证通过）
• 鸿蒙SDK API Version 9+
• 测试设备：Hi3516开发板或MatePad实机（需开启开发者模式）

2.2 关键依赖声明

在模块的 package.json 中需要明确定义鸿蒙专属依赖：

"peerDependencies": {
  "react-native-harmony": "^0.72.0-harmony.4",
  "@ohos/fileio": "^1.0.0",
  "@ohos.abilityAccessCtrl": "^1.0.0"
}

2.3 鸿蒙权限配置

在 module.json5 中声明相册访问权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_IMAGEVIDEO",
        "reason": "$string:permission_camera_roll_desc"
      },
      {
        "name": "ohos.permission.WRITE_IMAGEVIDEO", 
        "reason": "$string:permission_camera_roll_desc"
      }
    ]
  }
}

3. 核心接口鸿蒙化改造

3.1 文件保存功能适配

原始Android实现依赖MediaStore.Images.Media.insertImage，鸿蒙版本需要重写为：

import photoAccessHelper from '@ohos.file.photoAccessHelper';

async function saveToHarmonyAlbum(uri: string, albumName: string) {
  const phAccessHelper = photoAccessHelper.getPhotoAccessHelper(this.context);
  const createOpt = {
    title: Date.now().toString() + '.jpg',
    relativePath: `Pictures/${albumName}/`
  };
  
  try {
    const asset = await phAccessHelper.createAsset(createOpt);
    const fd = await asset.open('rw');
    await fs.copy(fd, uri); // 实际文件写入操作
    await asset.close(fd);
    return `harmony://media/${asset.id}`;
  } catch (err) {
    console.error('Save failed:', err.code, err.message);
    throw err;
  }
}

3.2 相册查询接口改造

鸿蒙的媒体检索采用谓词查询方式：

async function getPhotos(params: GetPhotosParams) {
  const phAccessHelper = photoAccessHelper.getPhotoAccessHelper(this.context);
  const fetchOptions = {
    selections: `date_modified > ? AND ${photoAccessHelper.PhotoKeys.SIZE} > ?`,
    selectionArgs: [params.fromTime || 0, params.minimumSize || 0],
    order: `${photoAccessHelper.PhotoKeys.DATE_MODIFIED} DESC`
  };

  const assets = await phAccessHelper.getAssets(fetchOptions);
  return assets.map(asset => ({
    uri: `harmony://media/${asset.id}`,
    filename: asset.title,
    height: asset.get(photoAccessHelper.PhotoKeys.HEIGHT),
    width: asset.get(photoAccessHelper.PhotoKeys.WIDTH),
    timestamp: asset.get(photoAccessHelper.PhotoKeys.DATE_MODIFIED)
  }));
}

4. 性能优化与异常处理

4.1 大文件传输优化

针对超过10MB的媒体文件，建议采用分块写入策略：

1. 使用 createAsset 创建空文件占位
2. 通过 open('rw') 获取文件描述符
3. 采用流式分块写入（建议256KB/块）
4. 最后调用 close 释放资源

4.2 常见错误码处理

错误码	含义	解决方案
13900001	权限拒绝	检查动态权限是否已授权
13900011	存储空间不足	提示用户清理存储
13900025	文件路径非法	验证URI格式是否符合harmony://media/格式
13900032	分布式设备未连接	检查设备组网状态

5. 实际应用案例

5.1 图片保存完整流程

import { CameraRoll } from 'react-native-camera-roll-harmony';

// 保存网络图片
async function saveNetworkImage(imageUrl: string) {
  try {
    const downloadPath = await downloadFile(imageUrl);
    const savedUri = await CameraRoll.save(downloadPath, {
      type: 'photo',
      album: 'MyApp'
    });
    console.log('Image saved at:', savedUri);
  } catch (error) {
    if (error.code === 13900001) {
      showPermissionRequestDialog();
    } else {
      showErrorToast(`保存失败: ${error.message}`);
    }
  }
}

5.2 相册分页加载实现

const PAGE_SIZE = 20;

function PhotoGallery() {
  const [photos, setPhotos] = useState([]);
  const [loading, setLoading] = useState(false);

  const loadMore = useCallback(async () => {
    if (loading) return;
    
    setLoading(true);
    try {
      const newPhotos = await CameraRoll.getPhotos({
        first: PAGE_SIZE,
        after: photos[photos.length - 1]?.timestamp
      });
      setPhotos(prev => [...prev, ...newPhotos]);
    } finally {
      setLoading(false);
    }
  }, [photos]);

  return <FlatList
    data={photos}
    renderItem={renderItem}
    onEndReached={loadMore}
  />;
}

6. 调试技巧与性能监控

6.1 日志过滤配置

在DevEco Studio的logcat过滤器中添加：

tag:ReactNative tag:CameraRollHarmony level:DEBUG

6.2 性能埋点建议

关键操作添加性能统计：

import hiTraceMeter from '@ohos.hiTraceMeter';

async function tracedSave(uri: string) {
  const traceId = hiTraceMeter.startTrace('CameraRollSave', 1000);
  try {
    // ...保存操作
    hiTraceMeter.finishTrace(traceId);
  } catch (err) {
    hiTraceMeter.finishTrace(traceId);
    throw err;
  }
}

7. 兼容性处理方案

7.1 多平台代码组织

建议采用平台后缀区分实现：

react-native-camera-roll/
├── android/
├── ios/
├── harmony/
│   ├── CameraRollHarmony.ts
│   └── NativeModules.ts
└── index.js

index.js中实现自动平台检测：

let implementation;
if (Platform.OS === 'harmony') {
  implementation = require('./harmony');
} else {
  implementation = require('./common');
}
module.exports = implementation;

7.2 降级策略设计

当鸿蒙特有API不可用时，可回退到基础文件操作：

async function fallbackSave(uri: string) {
  const destPath = path.join(
    globalThis.context.filesDir,
    'Pictures/MyApp',
    `${Date.now()}.jpg`
  );
  await fs.copyFile(uri, destPath);
  return destPath;
}

8. 安全增强措施

8.1 输入验证机制

对所有传入的URI进行安全校验：

function validateUri(uri: string) {
  if (!uri) throw new Error('URI cannot be empty');
  
  const harmonyPattern = /^harmony:\/\/media\/[0-9a-f-]{36}$/;
  const filePattern = /^file:\/\/\/.+\.(jpg|png|gif)$/i;
  
  if (!harmonyPattern.test(uri) && !filePattern.test(uri)) {
    throw new Error(`Invalid URI format: ${uri}`);
  }
}

8.2 沙箱访问控制

通过FileDescriptor限制文件访问范围：

async function secureOpen(asset: photoAccessHelper.PhotoAsset) {
  const fd = await asset.open('rw', {
    mode: 0o600, // 仅当前应用可读写
    flags: fs.OpenMode.CREATE | fs.OpenMode.TRUNC
  });
  return fd;
}

9. 测试验证方案

9.1 单元测试重点

describe('CameraRollHarmony', () => {
  it('should save image to specified album', async () => {
    const testUri = 'file:///test.jpg';
    const spyCreate = jest.spyOn(photoAccessHelper, 'createAsset');
    
    await CameraRoll.save(testUri, { album: 'TestAlbum' });
    
    expect(spyCreate).toHaveBeenCalledWith(
      expect.objectContaining({
        relativePath: 'Pictures/TestAlbum/'
      })
    );
  });
});

9.2 真机测试要点

1. 在不同存储状态下的表现（剩余空间<100MB时）
2. 分布式设备间的媒体文件同步场景
3. 快速连续保存100+图片的压力测试
4. 权限动态回收后的错误恢复流程

10. 扩展能力集成

10.1 图片信息提取

结合鸿蒙的ImageSource API增强元数据获取：

async function getImageMetadata(asset: photoAccessHelper.PhotoAsset) {
  const fd = await asset.open('r');
  const imageSource = image.createImageSource(fd);
  const metadata = await imageSource.getImageProperty('BitsPerSample');
  await asset.close(fd);
  return metadata;
}

10.2 智能相册分类

利用鸿蒙的AI能力实现自动分类：

import imageClassification from '@ohos.ai.imageClassification';

async function classifyImage(asset: photoAccessHelper.PhotoAsset) {
  const fd = await asset.open('r');
  const classifier = await imageClassification.createImageClassification();
  const results = await classifier.classify(fd);
  await asset.close(fd);
  
  return results.map(item => ({
    label: item.name,
    confidence: item.confidence
  }));
}

在实际项目集成中，我们发现鸿蒙的媒体文件URI生命周期管理需要特别注意——当应用退到后台时，系统可能会回收临时文件访问权限。建议对返回的harmony://media/ URI进行持久化存储时，同时记录对应的PhotoAsset ID，在需要再次访问时通过photoAccessHelper.getAssetById重新获取访问权限