React Native图片保存功能在鸿蒙OS的适配实践

1. 项目概述

在鸿蒙生态中集成React Native能力正成为开发者关注的热点。这次我们要解决一个具体而常见的需求：在HarmonyOS平台上实现React Native应用的图片保存到相册功能。react-native-camera-roll作为React Native生态中广泛使用的相册操作库，其鸿蒙化适配具有典型意义。

这个方案的价值在于：

• 填补React Native鸿蒙化生态中媒体存储能力的空白
• 为后续其他React Native媒体类库的鸿蒙适配提供参考模板
• 解决跨平台应用中"最后一公里"的本地化存储问题

2. 核心需求解析

2.1 功能定位

react-native-camera-roll的核心功能包括：

• 将图片/视频保存到系统相册
• 从相册读取媒体文件
• 查询相册内容
• 删除相册中的项目

在鸿蒙平台，我们需要重点关注保存功能，因为：

1. 这是最基础且高频使用的功能
2. 鸿蒙的媒体存储机制与Android/iOS存在差异
3. 涉及敏感权限处理，需要特殊适配

2.2 技术挑战点

鸿蒙平台的特殊性带来以下技术难点：

• 媒体文件URI处理方式不同
• 权限申请流程差异
• 相册数据库访问接口不兼容
• 文件存储路径规则变化

3. 环境准备与工具链

3.1 基础环境配置

需要准备：

• DevEco Studio 3.1+
• HarmonyOS SDK API 9+
• React Native 0.72+
• Node.js 18+

配置要点：

bash复制# 安装鸿蒙开发工具
npm install -g @ohos/hpm-cli
hpm install @ohos/react-native-harmony

3.2 原生模块开发环境

由于需要开发鸿蒙原生模块，需配置：

• Java JDK 11
• Gradle 7.5+
• Ohos SDK路径正确配置

在项目的build.gradle中添加：

groovy复制dependencies {
    implementation 'io.github.ohos:react-native-harmony:0.72.1'
}

4. 库的鸿蒙化改造

4.1 项目结构改造

原始React Native库的Android/iOS原生代码需要转换为鸿蒙架构：

code复制react-native-camera-roll-harmony/
├── oh-package.json
├── src/
│   ├── main/
│   │   ├── ets/
│   │   │   ├── CameraRollModule.ets
│   │   │   └── types/
│   │   └── resources/
│   └── test/
└── build.gradle

4.2 核心功能实现

保存到相册的核心逻辑需要重写：

typescript复制// CameraRollModule.ets
import mediaLibrary from '@ohos.multimedia.mediaLibrary'

async function saveToCameraRoll(uri: string): Promise<boolean> {
    const media = mediaLibrary.getMediaLibrary(context)
    const publicDir = mediaLibrary.DirectoryType.DIR_IMAGE
    
    try {
        const asset = await media.createAsset(
            mediaLibrary.MediaType.IMAGE,
            uri.substring(uri.lastIndexOf('/') + 1),
            publicDir
        )
        return !!asset
    } catch (e) {
        console.error('Save failed:', e)
        return false
    }
}

5. 权限系统适配

5.1 鸿蒙权限声明

在module.json5中添加：

json复制{
    "module": {
        "requestPermissions": [
            {
                "name": "ohos.permission.READ_MEDIA",
                "reason": "Required to access photos"
            },
            {
                "name": "ohos.permission.WRITE_MEDIA",
                "reason": "Required to save photos"
            }
        ]
    }
}

5.2 动态权限申请

实现权限检查逻辑：

typescript复制import abilityAccessCtrl from '@ohos.abilityAccessCtrl'

async function checkPermissions(): Promise<boolean> {
    const atManager = abilityAccessCtrl.createAtManager()
    try {
        const status = await atManager.requestPermissionsFromUser(
            context,
            ['ohos.permission.READ_MEDIA', 'ohos.permission.WRITE_MEDIA']
        )
        return status.authResults.every(granted => granted === 0)
    } catch (e) {
        console.error('Permission request failed:', e)
        return false
    }
}

6. JS层接口适配

6.1 类型定义

保持与原始库一致的TypeScript定义：

typescript复制type SaveToCameraRollOptions = {
    type?: 'photo' | 'video' | 'auto'
    album?: string
}

interface CameraRollStatic {
    save(uri: string, options?: SaveToCameraRollOptions): Promise<string>
    // 其他方法...
}

6.2 桥接实现

JS与原生模块的交互层：

typescript复制import { TurboModule, TurboModuleRegistry } from 'react-native'

export interface Spec extends TurboModule {
    saveToCameraRoll(uri: string): Promise<string>
    // 其他方法...
}

export default TurboModuleRegistry.get<Spec>('CameraRollModule') as Spec | null

7. 测试与验证

7.1 单元测试

编写Ets测试用例：

typescript复制import { describe, it, expect } from '@ohos/hypium'
import CameraRollModule from '../src/main/ets/CameraRollModule'

describe('CameraRollTest', () => {
    it('testSaveImage', 0, async () => {
        const testUri = 'file://data/storage/el2/base/test.jpg'
        const result = await CameraRollModule.saveToCameraRoll(testUri)
        expect(result).assertTrue()
    })
})

7.2 真机测试要点

测试时需要关注：

1. 不同文件来源（网络图片、本地文件、base64）
2. 大文件处理（超过10MB）
3. 并发保存操作
4. 低存储空间情况

8. 性能优化

8.1 内存管理

鸿蒙平台的特殊注意事项：

typescript复制// 大文件处理示例
async function saveLargeFile(uri: string): Promise<boolean> {
    const media = mediaLibrary.getMediaLibrary(context)
    const fd = await fileio.open(uri, 0o2)  // 只读模式打开
    
    try {
        const buffer = new ArrayBuffer(1024 * 1024) // 1MB缓冲区
        let offset = 0
        let read
        
        while ((read = await fileio.read(fd, buffer, { offset })) > 0) {
            // 分块处理...
            offset += read
        }
        
        return true
    } finally {
        fileio.close(fd)
    }
}

8.2 线程模型

建议采用Worker线程处理IO操作：

json复制// module.json5
{
    "abilities": [
        {
            "name": "CameraRollWorker",
            "type": "service",
            "backgroundModes": ["dataTransfer"]
        }
    ]
}

9. 常见问题解决

9.1 文件路径问题

鸿蒙与Android的路径差异对照表：

9.2 权限拒绝处理

推荐的重试机制实现：

typescript复制async function saveWithRetry(uri: string, retries = 3): Promise<boolean> {
    for (let i = 0; i < retries; i++) {
        try {
            return await saveToCameraRoll(uri)
        } catch (e) {
            if (e.code === 201 && i < retries - 1) {
                await new Promise(resolve => setTimeout(resolve, 1000))
                continue
            }
            throw e
        }
    }
    return false
}

10. 扩展功能实现

10.1 相册分组支持

鸿蒙相册分组实现：

typescript复制async function saveToAlbum(uri: string, albumName: string): Promise<boolean> {
    const media = mediaLibrary.getMediaLibrary(context)
    let album = await media.getAlbum(albumName)
    
    if (!album) {
        album = await media.createAlbum(albumName)
    }
    
    const fileAsset = await media.createAsset(
        mediaLibrary.MediaType.IMAGE,
        uri.substring(uri.lastIndexOf('/') + 1),
        mediaLibrary.DirectoryType.DIR_IMAGE
    )
    
    return album.addAsset(fileAsset)
}

10.2 Base64支持

Base64图片处理方案：

typescript复制import base64 from '@ohos.base64'
import fileio from '@ohos.fileio'

async function saveBase64(base64Data: string): Promise<string> {
    const buffer = base64.decode(base64Data)
    const tempPath = '/data/storage/el2/base/temp_' + Date.now() + '.jpg'
    
    await fileio.write(tempPath, buffer)
    const result = await saveToCameraRoll(tempPath)
    await fileio.unlink(tempPath)
    
    return result
}

11. 工程化建议

11.1 版本管理策略

推荐采用多平台兼容的版本号规则：

code复制"version": "5.0.0-harmony.1"

在package.json中配置平台特定入口：

json复制{
    "react-native": {
        "harmony": "./src/main/ets/CameraRollModule.ets",
        "android": "./android",
        "ios": "./ios"
    }
}

11.2 持续集成

鸿蒙平台的CI配置示例：

yaml复制# .github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: hpm install
      - run: npm run build:harmony

12. 兼容性处理

12.1 多平台兼容方案

建议的架构设计：

typescript复制// index.ts
import { Platform } from 'react-native'

let CameraRoll: CameraRollStatic

if (Platform.OS === 'harmony') {
    CameraRoll = require('./harmony').default
} else {
    CameraRoll = require('./src').default
}

export default CameraRoll

12.2 API差异处理

关键API差异对照实现：

typescript复制function getSaveFunction(): (uri: string) => Promise<string> {
    if (Platform.OS === 'harmony') {
        return require('./harmony').saveToCameraRoll
    } else if (Platform.OS === 'android') {
        return require('./android').saveToCameraRoll
    } else {
        return require('./ios').saveToCameraRoll
    }
}

13. 调试技巧

13.1 日志输出优化

建议的调试日志配置：

typescript复制class Logger {
    static debug(...args: any[]) {
        if (__DEV__) {
            console.debug('[CameraRoll]', ...args)
        }
    }
    
    static error(...args: any[]) {
        console.error('[CameraRoll]', ...args)
    }
}

// 使用示例
Logger.debug('Saving file:', uri)

13.2 鸿蒙开发者工具使用

关键调试功能：

1. HiLog查看器：过滤CameraRoll标签
2. 分布式调度跟踪：分析跨线程调用
3. 内存分析工具：检测媒体文件处理时的内存泄漏

14. 安全注意事项

14.1 文件安全

必须实现的校验逻辑：

typescript复制import fileio from '@ohos.fileio'

async function validateFile(uri: string): Promise<boolean> {
    try {
        const stat = await fileio.stat(uri)
        return stat.isFile && stat.size > 0
    } catch (e) {
        return false
    }
}

14.2 权限管理

推荐的最佳实践：

1. 按需申请权限
2. 提供友好的权限拒绝处理
3. 敏感操作前二次确认
4. 定期清理临时文件

15. 性能指标

15.1 基准测试数据

典型场景下的性能表现（测试设备：MatePad Pro 12.6）：

15.2 优化建议

1. 大文件采用流式处理
2. 批量操作使用队列控制
3. 避免主线程IO操作
4. 合理设置缓冲区大小

16. 实际应用案例

16.1 社交应用场景

典型实现流程：

typescript复制async function shareAndSave(imageUri: string) {
    try {
        // 先保存到相册
        const savedUri = await CameraRoll.save(imageUri)
        
        // 然后分享
        await Share.open({
            url: `file://${savedUri}`,
            type: 'image/jpeg'
        })
    } catch (e) {
        Alert.alert('操作失败', e.message)
    }
}

16.2 电商应用场景

商品图片保存优化方案：

typescript复制async function saveProductImage(url: string) {
    // 先下载
    const response = await fetch(url)
    const blob = await response.blob()
    
    // 转Base64处理
    const base64Data = await blobToBase64(blob)
    
    // 保存
    return CameraRoll.saveBase64(base64Data)
}

17. 升级维护策略

17.1 API版本兼容

推荐的做法：

typescript复制// 版本检测逻辑
function checkHarmonyVersion(): boolean {
    const version = system.version.split('.').map(Number)
    return version[0] >= 3 && version[1] >= 1
}

// 条件式API调用
async function saveWithFallback(uri: string) {
    if (checkHarmonyVersion()) {
        return CameraRoll.save(uri)
    } else {
        return legacySave(uri)
    }
}

17.2 废弃API处理

示例迁移指南：

markdown复制## 从v4迁移到v5

### 变更内容
- 移除了`getPhotos`方法，改用`queryMedia`
- `save`方法现在返回完整URI而不仅是布尔值

### 迁移步骤
1. 替换所有`getPhotos`调用为：
   ```typescript
   // 旧代码
   CameraRoll.getPhotos(params)
   
   // 新代码
   CameraRoll.queryMedia(params)

code复制
## 18. 社区贡献指南

### 18.1 开发规范
代码提交要求：
1. TypeScript严格模式
2. 完整的JSDoc注释
3. 配套单元测试
4. 遵循鸿蒙API设计规范

### 18.2 测试覆盖率要求
最低标准：
- 业务逻辑覆盖率 ≥80%
- 异常处理覆盖率 ≥90%
- 核心API覆盖率 100%

## 19. 替代方案对比

### 19.1 与其他库的对比

| 特性 | react-native-camera-roll | react-native-fs | react-native-image-picker |
|------|-------------------------|----------------|--------------------------|
| 保存到相册 | ✅ | ❌ | ✅ |
| 读取相册 | ✅ | ❌ | ✅ |
| 文件管理 | ❌ | ✅ | ❌ |
| 鸿蒙支持 | 需适配 | 需适配 | 需适配 |
| 性能 | 优 | 良 | 中 |

### 19.2 原生方案对比
直接使用鸿蒙媒体库的优势：
1. 更好的性能
2. 更精细的权限控制
3. 完整的相册管理能力

缺点：
1. 需要单独维护鸿蒙实现
2. 增加包体积
3. 学习成本较高

## 20. 未来扩展方向

### 20.1 云相册集成
可能的扩展点：
```typescript
interface CloudSyncOptions {
    autoUpload: boolean
    cloudService: 'huawei' | 'other'
}

function enableCloudSync(options: CloudSyncOptions): void {
    // 实现云同步逻辑
}

20.2 智能相册功能

基于鸿蒙AI能力的扩展：

typescript复制async function analyzePhoto(uri: string): Promise<PhotoAnalysis> {
    const image = image.createImageSource(uri)
    const pixelMap = await image.createPixelMap()
    
    return ImageAI.analyze(pixelMap, {
        detectFaces: true,
        recognizeObjects: true,
        estimateQuality: true
    })
}

在完成这个react-native-camera-roll的鸿蒙化适配后，我发现有几个关键点值得特别注意：首先，鸿蒙的媒体存储API虽然设计良好，但文档示例较少，需要开发者自己探索；其次，权限系统的严格性要求我们编写更健壮的错误处理逻辑；最后，与React Native的桥接部分要特别注意线程安全，避免UI阻塞。