HarmonyOS鸿蒙Next开发者技术支持-多格式图片保存到应用沙箱实现案例

一、项目概述

1.1 功能特性

基于HarmonyOS最新API实现

多格式图片支持：JPEG、PNG、WebP、GIF、BMP等格式

智能图片压缩与质量调整

沙箱目录管理：自动创建分类目录

图片元数据保留：EXIF信息处理

批量图片操作支持

图片预览与分享功能

二、架构设计

2.1 核心组件结构

图片保存系统
├── ImageSaver.ets (图片保存核心)
├── ImageCompressor.ets (图片压缩器)
├── ImageGallery.ets (图片画廊)
├── ImageUtils.ets (图片工具类)
├── FileManager.ets (文件管理器)
├── PermissionManager.ets (权限管理)
└── ImageShare.ets (图片分享)

2.2 数据模型定义

// ImageModel.ets
// 图片保存配置
export interface SaveConfig {
  format: ImageFormat;           // 图片格式
  quality: number;               // 图片质量(0-100)
  maxWidth?: number;             // 最大宽度
  maxHeight?: number;            // 最大高度
  preserveExif: boolean;         // 是否保留EXIF信息
  directory: string;             // 保存目录
  filename?: string;             // 文件名
}

// 图片格式枚举
export enum ImageFormat {
  JPEG = 'jpeg',
  PNG = 'png', 
  WEBP = 'webp',
  GIF = 'gif',
  BMP = 'bmp'
}

// 图片信息
export interface ImageInfo {
  uri: string;                   // 图片URI
  width: number;                 // 宽度
  height: number;                // 高度
  size: number;                  // 文件大小
  format: ImageFormat;           // 格式
  mimeType: string;              // MIME类型
  exif?: Record<string, any>;    // EXIF信息
  createTime: number;            // 创建时间
}

// 保存结果
export interface SaveResult {
  success: boolean;              // 是否成功
  filePath?: string;             // 文件路径
  error?: string;                // 错误信息
  fileSize?: number;             // 文件大小
  compressed?: boolean;          // 是否压缩
}

// 默认配置
export class ImageDefaultConfig {
  static readonly DEFAULT_CONFIG: SaveConfig = {
    format: ImageFormat.JPEG,
    quality: 85,
    preserveExif: true,
    directory: 'images'
  };
}

这里定义了图片保存系统的核心数据模型。SaveConfig接口包含图片保存的所有配置参数。ImageFormat枚举定义了支持的图片格式。ImageInfo接口记录图片的详细信息。

三、核心实现

3.1 图片保存核心组件

// ImageSaver.ets
[@Component](/user/Component)
export struct ImageSaver {
  [@State](/user/State) private saveConfig: SaveConfig = ImageDefaultConfig.DEFAULT_CONFIG;
  [@State](/user/State) private isSaving: boolean = false;
  [@State](/user/State) private saveProgress: number = 0;
  
  private fileManager: FileManager = new FileManager();
  private imageUtils: ImageUtils = new ImageUtils();
  
  // 保存图片到沙箱
  async saveImageToSandbox(imageUri: string, config?: SaveConfig): Promise<SaveResult> {
    if (this.isSaving) {
      return { success: false, error: '正在保存中，请稍后' };
    }
    
    this.isSaving = true;
    this.saveProgress = 0;
    
    try {
      const saveConfig = config || this.saveConfig;
      
      // 步骤1：检查权限
      const hasPermission = await this.checkPermissions();
      if (!hasPermission) {
        return { success: false, error: '无文件读写权限' };
      }
      
      // 步骤2：创建保存目录
      const dirPath = await this.createSaveDirectory(saveConfig.directory);
      
      // 步骤3：生成文件名
      const filename = this.generateFilename(saveConfig);
      
      // 步骤4：处理图片（压缩、格式转换等）
      const processedImage = await this.processImage(imageUri, saveConfig);
      this.saveProgress = 50;
      
      // 步骤5：保存到文件
      const filePath = `${dirPath}/${filename}`;
      await this.fileManager.writeFile(filePath, processedImage.data);
      this.saveProgress = 100;
      
      // 步骤6：更新媒体库
      await this.updateMediaLibrary(filePath);
      
      return {
        success: true,
        filePath: filePath,
        fileSize: processedImage.data.length,
        compressed: processedImage.compressed
      };
      
    } catch (error) {
      return { success: false, error: error.message };
    } finally {
      this.isSaving = false;
      this.saveProgress = 0;
    }
  }
  
  // 创建保存目录
  private async createSaveDirectory(directory: string): Promise<string> {
    const context = getContext(this) as common.UIAbilityContext;
    const dirPath = `${context.filesDir}/${directory}`;
    
    try {
      await fs.access(dirPath);
    } catch (error) {
      await fs.mkdir(dirPath);
    }
    
    return dirPath;
  }
  
  // 生成文件名
  private generateFilename(config: SaveConfig): string {
    const timestamp = new Date().getTime();
    const random = Math.random().toString(36).substring(2, 8);
    
    if (config.filename) {
      return `${config.filename}_${timestamp}_${random}.${config.format}`;
    }
    
    return `image_${timestamp}_${random}.${config.format}`;
  }

ImageSaver组件是图片保存的核心，负责整个保存流程。saveImageToSandbox方法处理从图片URI到文件保存的完整流程，包括权限检查、目录创建、图片处理和文件保存。

3.2 图片处理组件

// ImageProcessor.ets
[@Component](/user/Component)
export struct ImageProcessor {
  [@State](/user/State) private processingConfig: ProcessingConfig = {
    maxWidth: 2048,
    maxHeight: 2048,
    quality: 85,
    format: ImageFormat.JPEG
  };
  
  // 处理图片（压缩、格式转换、EXIF处理）
  async processImage(uri: string, config: SaveConfig): Promise<ProcessedImage> {
    try {
      // 步骤1：读取图片信息
      const imageInfo = await this.getImageInfo(uri);
      
      // 步骤2：解码图片
      const imageSource = image.createImageSource(uri);
      const pixelMap = await imageSource.createPixelMap();
      
      // 步骤3：调整尺寸（如果需要）
      const resizedPixelMap = await this.resizeImage(pixelMap, config);
      
      // 步骤4：编码为指定格式
      const imagePacker = image.createImagePacker();
      const packOptions = this.getPackOptions(config);
      
      const arrayBuffer = await imagePacker.packing(resizedPixelMap, packOptions);
      
      // 步骤5：处理EXIF信息
      let finalData = new Uint8Array(arrayBuffer);
      if (config.preserveExif && imageInfo.exif) {
        finalData = await this.preserveExifData(finalData, imageInfo.exif);
      }
      
      return {
        data: finalData,
        width: resizedPixelMap.width,
        height: resizedPixelMap.height,
        compressed: resizedPixelMap.width !== imageInfo.width || 
                   resizedPixelMap.height !== imageInfo.height
      };
      
    } catch (error) {
      throw new Error(`图片处理失败: ${error.message}`);
    }
  }
  
  // 调整图片尺寸
  private async resizeImage(pixelMap: image.PixelMap, config: SaveConfig): Promise<image.PixelMap> {
    const { width, height } = pixelMap;
    
    // 检查是否需要调整尺寸
    if ((!config.maxWidth || width <= config.maxWidth) && 
        (!config.maxHeight || height <= config.maxHeight)) {
      return pixelMap;
    }
    
    // 计算新尺寸
    const newSize = this.calculateNewSize(width, height, config.maxWidth, config.maxHeight);
    
    // 创建图片源并调整尺寸
    const imageSource = image.createImageSource(pixelMap);
    const resizeOptions = {
      desiredSize: {
        width: newSize.width,
        height: newSize.height
      }
    };
    
    return await imageSource.createPixelMap(resizeOptions);
  }
  
  // 获取编码选项
  private getPackOptions(config: SaveConfig): image.PackingOptions {
    const formatMap = {
      [ImageFormat.JPEG]: 'image/jpeg',
      [ImageFormat.PNG]: 'image/png',
      [ImageFormat.WEBP]: 'image/webp',
      [ImageFormat.GIF]: 'image/gif',
      [ImageFormat.BMP]: 'image/bmp'
    };
    
    return {
      format: formatMap[config.format],
      quality: config.quality
    };
  }

ImageProcessor组件负责图片的处理逻辑，包括尺寸调整、格式转换和EXIF信息处理。processImage方法实现了完整的图片处理流程。

3.3 文件管理器组件

// FileManager.ets
[@Component](/user/Component)
export struct FileManager {
  [@State](/user/State) private fileOperations: Map<string, FileOperation> = new Map();
  
  // 写入文件到沙箱
  async writeFile(filePath: string, data: Uint8Array): Promise<void> {
    try {
      // 创建文件流
      const file = await fs.open(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
      
      // 写入数据
      await fs.write(file.fd, data);
      
      // 关闭文件
      await fs.close(file.fd);
      
    } catch (error) {
      throw new Error(`文件写入失败: ${error.message}`);
    }
  }
  
  // 从沙箱读取文件
  async readFile(filePath: string): Promise<Uint8Array> {
    try {
      const file = await fs.open(filePath, fs.OpenMode.READ_ONLY);
      const fileInfo = await fs.stat(filePath);
      
      const buffer = new ArrayBuffer(fileInfo.size);
      await fs.read(file.fd, buffer);
      await fs.close(file.fd);
      
      return new Uint8Array(buffer);
      
    } catch (error) {
      throw new Error(`文件读取失败: ${error.message}`);
    }
  }
  
  // 获取沙箱文件列表
  async getSandboxFiles(directory: string): Promise<SandboxFile[]> {
    try {
      const context = getContext(this) as common.UIAbilityContext;
      const dirPath = `${context.filesDir}/${directory}`;
      
      const files = await fs.listFile(dirPath);
      const result: SandboxFile[] = [];
      
      for (const file of files) {
        const filePath = `${dirPath}/${file}`;
        const fileInfo = await fs.stat(filePath);
        
        result.push({
          name: file,
          path: filePath,
          size: fileInfo.size,
          mtime: fileInfo.mtime,
          isDirectory: fileInfo.isDirectory()
        });
      }
      
      return result.sort((a, b) => b.mtime - a.mtime); // 按修改时间排序
      
    } catch (error) {
      return [];
    }
  }

FileManager组件封装了文件系统操作，提供安全的文件读写功能。writeFile方法将数据写入沙箱文件，getSandboxFiles方法获取指定目录下的文件列表。

3.4 权限管理组件

// PermissionManager.ets
[@Component](/user/Component)
export struct PermissionManager {
  [@State](/user/State) private permissions: Map<string, PermissionStatus> = new Map();
  
  // 检查并申请权限
  async checkAndRequestPermissions(): Promise<boolean> {
    const permissions = [
      'ohos.permission.READ_MEDIA',
      'ohos.permission.WRITE_MEDIA',
      'ohos.permission.MEDIA_LOCATION'
    ];
    
    try {
      for (const permission of permissions) {
        const status = await abilityAccessCtrl.createAtManager().verifyAccessToken(
          abilityAccessCtrl.TokenType.APPLICATION, 
          permission
        );
        
        if (status !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
          // 申请权限
          const requestResult = await abilityAccessCtrl.createAtManager().requestPermissionsFromUser(
            getContext(this) as common.UIAbilityContext,
            [permission]
          );
          
          if (requestResult.authResults[0] !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
            return false;
          }
        }
      }
      
      return true;
      
    } catch (error) {
      return false;
    }
  }
  
  // 检查单个权限
  async checkPermission(permission: string): Promise<boolean> {
    try {
      const status = await abilityAccessCtrl.createAtManager().verifyAccessToken(
        abilityAccessCtrl.TokenType.APPLICATION, 
        permission
      );
      
      return status === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
      
    } catch (error) {
      return false;
    }
  }
}

PermissionManager组件处理应用权限的检查和申请。checkAndRequestPermissions方法检查并申请图片保存所需的所有权限。

四、高级特性

4.1 批量图片保存

// BatchImageSaver.ets
[@Component](/user/Component)
export struct BatchImageSaver {
  [@State](/user/State) private batchQueue: BatchImageItem[] = [];
  [@State](/user/State) private isProcessing: boolean = false;
  [@State](/user/State) private currentProgress: number = 0;
  [@State](/user/State) private totalProgress: number = 0;
  
  private imageSaver: ImageSaver = new ImageSaver();
  
  // 添加批量保存任务
  addBatchImages(images: BatchImageItem[]): void {
    this.batchQueue.push(...images);
    this.totalProgress = this.batchQueue.length;
  }
  
  // 执行批量保存
  async executeBatchSave(): Promise<BatchSaveResult> {
    if (this.isProcessing) {
      return { success: false, error: '批量处理正在进行中' };
    }
    
    this.isProcessing = true;
    this.currentProgress = 0;
    
    const results: BatchImageResult[] = [];
    let successCount = 0;
    let failCount = 0;
    
    try {
      for (const item of this.batchQueue) {
        try {
          const result = await this.imageSaver.saveImageToSandbox(item.uri, item.config);
          
          results.push({
            ...result,
            originalUri: item.uri,
            filename: item.config?.filename
          });
          
          if (result.success) {
            successCount++;
          } else {
            failCount++;
          }
          
        } catch (error) {
          results.push({
            success: false,
            error: error.message,
            originalUri: item.uri
          });
          failCount++;
        }
        
        this.currentProgress++;
        
        // 避免处理过快，添加小延迟
        await new Promise(resolve => setTimeout(resolve, 100));
      }
      
      return {
        success: true,
        results: results,
        total: this.batchQueue.length,
        successCount: successCount,
        failCount: failCount
      };
      
    } finally {
      this.isProcessing = false;
      this.batchQueue = [];
      this.currentProgress = 0;
      this.totalProgress = 0;
    }
  }
  
  // 构建批量进度显示
  [@Builder](/user/Builder)
  private buildBatchProgress() {
    if (!this.isProcessing) return;
    
    Column({ space: 8 }) {
      Text(`批量处理中... (${this.currentProgress}/${this.totalProgress})`)
        .fontSize(14)
        .fontColor('#666666')
      
      Progress({ 
        value: this.currentProgress, 
        total: this.totalProgress 
      })
        .width('80%')
      
      Text(`${Math.round((this.currentProgress / this.totalProgress) * 100)}%`)
        .fontSize(12)
        .fontColor('#999999')
    }
    .padding(16)
    .backgroundColor('#F5F5F5')
    .borderRadius(8)
    .margin({ bottom: 16 })
  }
}

BatchImageSaver组件实现批量图片保存功能。addBatchImages方法添加批量任务，executeBatchSave方法执行批量保存并显示进度。

4.2 图片画廊组件

// ImageGallery.ets
[@Component](/user/Component)
export struct ImageGallery {
  [@State](/user/State) private images: ImageInfo[] = [];
  [@State](/user/State) private selectedImage: ImageInfo | null = null;
  [@State](/user/State) private showPreview: boolean = false;
  
  private fileManager: FileManager = new FileManager();
  
  // 加载沙箱中的图片
  async loadSandboxImages(directory: string): Promise<void> {
    try {
      const files = await this.fileManager.getSandboxFiles(directory);
      const imageFiles = files.filter(file => 
        !file.isDirectory && this.isImageFile(file.name)
      );
      
      this.images = await Promise.all(
        imageFiles.map(async (file) => {
          const imageInfo = await this.getImageInfo(file.path);
          return {
            ...imageInfo,
            uri: `file://${file.path}`,
            createTime: file.mtime
          };
        })
      );
      
    } catch (error) {
      logger.error('加载图片失败:', error);
    }
  }
  
  // 判断是否为图片文件
  private isImageFile(filename: string): boolean {
    const imageExtensions = ['.jpg', '.jpeg', '.png', '.webp', '.gif', '.bmp'];
    return imageExtensions.some(ext => filename.toLowerCase().endsWith(ext));
  }
  
  // 构建图片网格
  [@Builder](/user/Builder)
  private buildImageGrid() {
    Grid() {
      ForEach(this.images, (image: ImageInfo) => {
        GridItem() {
          this.buildImageThumbnail(image)
        }
      })
    }
    .columnsTemplate('1fr 1fr 1fr')
    .rowsTemplate('1fr 1fr 1fr')
    .columnsGap(8)
    .rowsGap(8)
    .padding(16)
  }
  
  // 构建图片缩略图
  [@Builder](/user/Builder)
  private buildImageThumbnail(image: ImageInfo) {
    Stack({