HarmonyOS Image Kit 单图、多图及 GIF 编码全场景实践

HarmonyOS Image Kit 单图、多图及 GIF 编码全场景实践 | 极客日志

接口名称	功能描述	支持的输入对象	支持的输出格式	最低 API 版本
packToData	编码为 ArrayBuffer（内存流）	PixelMap、ImageSource	JPEG、WebP、PNG、HEIF	-
packToFile	直接编码为文件（写入磁盘）	PixelMap、ImageSource、Picture	JPEG、WebP、PNG、HEIF（Picture 仅支持 JPEG/HEIF）	-
packToDataFromPixelmapSequence	多 PixelMap 序列编码为 GIF 内存流	PixelMap 数组	GIF	18
packToFileFromPixelmapSequence	多 PixelMap 序列编码为 GIF 文件	PixelMap 数组	GIF	18

配置项	作用描述	可选值/注意事项	适用场景
format	输出格式（遵循 MIME 标准）	image/jpeg（.jpg/.jpeg）、image/webp（.webp）、image/png（.png）、image/heif（.heif）、image/gif（.gif）	所有编码场景
quality	压缩质量（仅有损格式支持）	0-100，数值越高质量越好、文件越大；PNG 是无损格式，此参数无效	JPEG、WebP 编码
desiredDynamicRange	动态范围（HDR 编码控制）	AUTO（自动识别）、SDR、HDR；仅 JPEG 格式支持 HDR 编码	HDR 图片编码
needsPackProperties	是否保留多图元数据	true/false；仅 Picture 多图编码时需要配置	多图（Picture）编码

// 图片编码工具类（基于 ImagePacker）
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo as fs } from '@kit.CoreFileKit';
import { Context } from '@kit.AbilityKit';

export class ImageEncoder {
  /**
   * 通用编码配置生成器
   * @param format 目标格式（MIME 标准）
   * @param quality 压缩质量（0-100，有损格式有效）
   * @param isHdr 是否需要 HDR 编码（仅 JPEG 支持）
   * @returns PackingOption
   */
  private static getPackingOption(
    format: string,
    quality: number = 90,
    isHdr: boolean = false
  ): image.PackingOption {
    const option: image.PackingOption = {
      format,
      quality: Math.max(0, Math.min(100, quality)), // 限制质量在 0-100 之间
    };
    // HDR 编码配置：仅 JPEG 格式支持，需资源本身是 HDR 且设备支持
    if (isHdr && format === 'image/jpeg') {
      option.desiredDynamicRange = image.PackingDynamicRange.AUTO;
    }
    return option;
  }

  /**
   * PixelMap 编码为 ArrayBuffer（内存流）
   * @param pixelMap 输入位图对象
   * @param format 目标格式
   * @param quality 压缩质量
   * @param isHdr 是否 HDR 编码
   * @returns 编码后的 ArrayBuffer
   */
  static async encodePixelMapToBuffer(
    pixelMap: image.PixelMap,
    format: string = 'image/jpeg',
    quality: number = 90,
    isHdr: boolean = false
  ): Promise<ArrayBuffer | undefined> {
    const imagePacker = image.createImagePacker();
    const packOpts = this.getPackingOption(format, quality, isHdr);
    try {
      const data = await imagePacker.packToData(pixelMap, packOpts);
      console.log(`PixelMap 编码为${format}成功，数据长度：${data.byteLength}字节`);
      return data;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`PixelMap 编码失败：code=${err.code}, message=${err.message}`);
      return undefined;
    }
  }

  /**
   * PixelMap 编码为文件
   * @param context 应用上下文
   * @param pixelMap 输入位图对象
   * @param fileName 输出文件名（含扩展名）
   * @param format 目标格式
   * @param quality 压缩质量
   * @param isHdr 是否 HDR 编码
   * @returns 输出文件路径
   */
  static async encodePixelMapToFile(
    context: Context,
    pixelMap: image.PixelMap,
    fileName: string,
    format: string = 'image/jpeg',
    quality: number = 90,
    isHdr: boolean = false
  ): Promise<string | undefined> {
    const imagePacker = image.createImagePacker();
    const packOpts = this.getPackingOption(format, quality, isHdr);
    // 输出路径：应用沙箱缓存目录（无需额外权限）
    const outputPath = `${context.cacheDir}/${fileName}`;
    try {
      // 打开文件：创建 + 读写模式
      const file = fs.openSync(outputPath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
      // 编码并写入文件
      await imagePacker.packToFile(pixelMap, file.fd, packOpts);
      console.log(`PixelMap 编码为文件成功：${outputPath}`);
      // 关闭文件句柄
      file.closeSync();
      return outputPath;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`PixelMap 编码为文件失败：code=${err.code}, message=${err.message}`);
      return undefined;
    }
  }

  /**
   * ImageSource 编码为文件（跳过 PixelMap，直接编码原文件）
   * @param context 应用上下文
   * @param imageSource 图片源对象
   * @param fileName 输出文件名
   * @param format 目标格式
   * @param quality 压缩质量
   * @returns 输出文件路径
   */
  static async encodeImageSourceToFile(
    context: Context,
    imageSource: image.ImageSource,
    fileName: string,
    format: string = 'image/png',
    quality: number = 90
  ): Promise<string | undefined> {
    const imagePacker = image.createImagePacker();
    const packOpts = this.getPackingOption(format, quality);
    const outputPath = `${context.cacheDir}/${fileName}`;
    try {
      const file = fs.openSync(outputPath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
      await imagePacker.packToFile(imageSource, file.fd, packOpts);
      file.closeSync();
      console.log(`ImageSource 编码为文件成功：${outputPath}`);
      return outputPath;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`ImageSource 编码失败：code=${err.code}, message=${err.message}`);
      return undefined;
    }
  }
}

// 完整流程：解码→编辑→编码保存
async function imageProcessFullFlow(context: Context, inputFileName: string) {
  // 1. 解码逻辑：获取 PixelMap
  const pixelMap = await decodeToPixelMap(context, inputFileName);
  if (!pixelMap) return;

  // 2. 编辑逻辑：裁剪 + 缩放
  const cropRegion = { x: 0, y: 0, size: { width: 500, height: 500 } };
  const croppedMap = await ImageEditor.cropImage(pixelMap, cropRegion);
  if (!croppedMap) {
    pixelMap.release();
    return;
  }

  // 3. 编码保存为 JPEG 文件（质量 95，非 HDR）
  const outputPath = await ImageEncoder.encodePixelMapToFile(
    context,
    croppedMap,
    'edited_avatar.jpg',
    'image/jpeg',
    95,
    false
  );

  // 4. 编码为 PNG 内存流（无损格式，用于网络上传）
  const pngBuffer = await ImageEncoder.encodePixelMapToBuffer(croppedMap, 'image/png');
  if (pngBuffer) {
    // 此处可调用网络接口上传
    console.log(`PNG 内存流准备完成，可用于上传：${pngBuffer.byteLength}字节`);
  }

  // 5. 释放资源（避免内存泄漏）
  pixelMap.release();
  croppedMap.release();
}

// 多图编码工具函数（Picture → 文件/ArrayBuffer）
export class PictureEncoder {
  /**
   * Picture 编码为文件
   * @param context 应用上下文
   * @param picture 多图对象
   * @param fileName 输出文件名
   * @param format 目标格式（仅支持 image/jpeg、image/heif）
   * @param quality 压缩质量
   * @returns 输出文件路径
   */
  static async encodeToFile(
    context: Context,
    picture: image.Picture,
    fileName: string,
    format: 'image/jpeg' | 'image/heif' = 'image/jpeg',
    quality: number = 90
  ): Promise<string | undefined> {
    // 校验格式（多图仅支持 JPEG/HEIF）
    if (!['image/jpeg', 'image/heif'].includes(format)) {
      console.error('多图编码仅支持 image/jpeg 和 image/heif 格式');
      return undefined;
    }
    const imagePacker = image.createImagePacker();
    const packOpts: image.PackingOption = {
      format,
      quality,
      desiredDynamicRange: image.PackingDynamicRange.AUTO,
      needsPackProperties: true, // 保留多图元数据，必须设置为 true
    };
    const outputPath = `${context.cacheDir}/${fileName}`;
    try {
      const file = fs.openSync(outputPath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
      await imagePacker.packToFile(picture, file.fd, packOpts);
      file.closeSync();
      console.log(`Picture 多图编码成功：${outputPath}`);
      return outputPath;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`Picture 编码失败：code=${err.code}, message=${err.message}`);
      return undefined;
    }
  }

  /**
   * Picture 编码为 ArrayBuffer
   * @param picture 多图对象
   * @param format 目标格式
   * @param quality 压缩质量
   * @returns 编码后的 ArrayBuffer
   */
  static async encodeToBuffer(
    picture: image.Picture,
    format: 'image/jpeg' | 'image/heif' = 'image/heif',
    quality: number = 90
  ): Promise<ArrayBuffer | undefined> {
    if (!['image/jpeg', 'image/heif'].includes(format)) {
      console.error('多图编码仅支持 image/jpeg 和 image/heif 格式');
      return undefined;
    }
    const imagePacker = image.createImagePacker();
    const packOpts: image.PackingOption = {
      format,
      quality,
      needsPackProperties: true,
    };
    try {
      const data = await imagePacker.packing(picture, packOpts); // 多图编码用 packing 接口
      console.log(`Picture 编码为内存流成功：${data.byteLength}字节`);
      return data;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`Picture 编码为 Buffer 失败：${err.message}`);
      return undefined;
    }
  }
}

// 调用示例：多图解码后直接编码
async function pictureEncodeDemo(context: Context, inputFileName: string) {
  // 1. 多图解码逻辑：获取 Picture 对象
  const picture = await decodeToPicture(context, inputFileName);
  if (!picture) return;

  // 2. 编码为 HEIF 格式文件（保留多图元数据）
  const heifPath = await PictureEncoder.encodeToFile(
    context,
    picture,
    'multi_image.heif',
    'image/heif',
    95
  );

  // 3. 释放 Picture 资源
  picture.release();
}

// GIF 序列编码工具（API18+）
export class GifEncoder {
  /**
   * 多个 PixelMap 编码为 GIF 文件
   * @param context 应用上下文
   * @param pixelMaps PixelMap 数组（按帧顺序排列）
   * @param fileName 输出文件名（扩展名.gif）
   * @param quality 压缩质量（0-100）
   * @returns 输出文件路径
   */
  static async encodeToGifFile(
    context: Context,
    pixelMaps: image.PixelMap[],
    fileName: string,
    quality: number = 80
  ): Promise<string | undefined> {
    // 校验 API 版本（需 API18+）
    const apiVersion = context.apiVersion;
    if (apiVersion < 18) {
      console.error('GIF 序列编码需要 API version 18 及以上');
      return undefined;
    }
    // 校验输入：至少需要 1 个 PixelMap
    if (pixelMaps.length === 0) {
      console.error('GIF 编码需要至少 1 个 PixelMap 帧');
      return undefined;
    }
    const imagePacker = image.createImagePacker();
    const packOpts: image.PackingOption = {
      format: 'image/gif', // GIF 格式的 MIME 类型
      quality,
    };
    const outputPath = `${context.cacheDir}/${fileName}`;
    try {
      const file = fs.openSync(outputPath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
      // 调用序列编码接口：PackToFileFromPixelmapSequence
      await imagePacker.packToFileFromPixelmapSequence(pixelMaps, file.fd, packOpts);
      file.closeSync();
      console.log(`GIF 序列编码成功：${outputPath}，共${pixelMaps.length}帧`);
      return outputPath;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`GIF 编码失败：code=${err.code}, message=${err.message}`);
      return undefined;
    } finally {
      // 释放所有帧的 PixelMap 资源
      pixelMaps.forEach((pmap) => pmap.release());
    }
  }

  /**
   * 多个 PixelMap 编码为 GIF 内存流（用于网络传输）
   * @param pixelMaps PixelMap 数组
   * @param quality 压缩质量
   * @returns GIF 内存流
   */
  static async encodeToGifBuffer(
    pixelMaps: image.PixelMap[],
    quality: number = 80
  ): Promise<ArrayBuffer | undefined> {
    if (pixelMaps.length === 0) {
      console.error('GIF 编码需要至少 1 个 PixelMap 帧');
      return undefined;
    }
    const imagePacker = image.createImagePacker();
    const packOpts: image.PackingOption = {
      format: 'image/gif',
      quality,
    };
    try {
      const data = await imagePacker.packToDataFromPixelmapSequence(pixelMaps, packOpts);
      console.log(`GIF 内存流编码成功：${data.byteLength}字节`);
      return data;
    } catch (error: unknown) {
      const err = error as BusinessError;
      console.error(`GIF 内存流编码失败：${err.message}`);
      return undefined;
    } finally {
      pixelMaps.forEach((pmap) => pmap.release());
    }
  }
}

// 调用示例：生成 3 帧 GIF 动画
async function generateGifDemo(context: Context) {
  // 1. 准备 3 个 PixelMap 帧（模拟动画帧，实际可从视频帧或图片序列获取）
  const frame1 = await decodeToPixelMap(context, 'frame1.jpg');
  const frame2 = await decodeToPixelMap(context, 'frame2.jpg');
  const frame3 = await decodeToPixelMap(context, 'frame3.jpg');
  const frames = [frame1, frame2, frame3].filter(Boolean) as image.PixelMap[];

  // 2. 编码为 GIF 文件
  const gifPath = await GifEncoder.encodeToGifFile(context, frames, 'animation.gif', 85);
}

// 保存到图库（基于文档说明的流程框架）
import { mediaLibrary } from '@kit.MediaLibraryKit';

async function saveToGallery(context: Context, filePath: string) {
  try {
    // 1. 获取 MediaLibrary 实例
    const ml = mediaLibrary.getMediaLibrary(context);
    // 2. 定义图库资产参数（图片类型）
    const assetInfo = {
      uri: filePath, // 沙箱中编码后的文件路径
      type: mediaLibrary.MediaType.IMAGE,
      displayName: 'edited_image.jpg',
    };
    // 3. 导入到图库（具体 API 以 Media Library Kit 文档为准）
    const asset = await ml.createAsset(assetInfo);
    console.log(`图片已保存到图库，资产 ID：${asset.assetId}`);
    // 4. 可选：删除沙箱临时文件
    fs.unlinkSync(filePath);
  } catch (error) {
    console.error(`保存到图库失败：${error}`);
  }
}

常见错误	后果	解决方案
MIME 格式与文件扩展名不匹配（如 format: 'image/jpeg'，扩展名.png）	文件无法打开	严格对应：image/jpeg→.jpg/.jpeg；image/png→.png；image/gif→.gif
多图编码选择 PNG 格式	编码失败（抛出异常）	多图仅支持 image/jpeg 和 image/heif
HDR 编码选择 PNG 格式	无效（HDR 仅支持 JPEG）	HDR 编码时 format 必须设为 image/jpeg

HarmonyOS Image Kit 单图、多图及 GIF 编码全场景实践

一、编码基础：先搞懂 ImagePacker 与核心配置

1.1 核心工具与支持格式

1.2 关键配置：PackingOption 解析

二、核心场景实战：编码功能手把手实现

2.1 单图编码：最常用场景（PixelMap/ImageSource）

2.1.1 工具类封装（统一编码逻辑）

2.1.2 调用示例（结合解码/编辑逻辑）

2.2 多图编码：Picture 对象专属场景

2.3 GIF 序列编码：API18+ 新增功能

2.4 保存到图库：编码后的收尾操作

三、避坑指南：这些错误千万别犯

3.1 格式与配置对应错误

3.2 版本与硬件兼容问题

3.3 资源释放遗漏

四、最佳实践：编码性能与质量双优化

五、总结：Image Kit 完整流程闭环

更多推荐文章

相关免费在线工具

HarmonyOS Image Kit 单图、多图及 GIF 编码全场景实践

一、编码基础：先搞懂 ImagePacker 与核心配置

1.1 核心工具与支持格式

1.2 关键配置：PackingOption 解析

二、核心场景实战：编码功能手把手实现

2.1 单图编码：最常用场景（PixelMap/ImageSource）

2.1.1 工具类封装（统一编码逻辑）

2.1.2 调用示例（结合解码/编辑逻辑）

2.2 多图编码：Picture 对象专属场景

2.3 GIF 序列编码：API18+ 新增功能

2.4 保存到图库：编码后的收尾操作

三、避坑指南：这些错误千万别犯

3.1 格式与配置对应错误

3.2 版本与硬件兼容问题

3.3 资源释放遗漏

四、最佳实践：编码性能与质量双优化

五、总结：Image Kit 完整流程闭环

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具