前言

图片的Base64编码和PixelMap转换是图片处理的基础操作，在图片上传、分享、缓存等场景中经常使用。@pura/harmony-utils 的 ImageUtil 封装了Base64与PixelMap互转方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ImageUtil转换核心API

ImageUtil 提供了以下图片转换方法：

方法	说明	返回类型	使用场景
base64ToPixelMap(base64)	Base64转PixelMap	PixelMap	图片解码展示
pixelMapToBase64(pixelMap)	PixelMap转Base64	string	图片上传/分享
base64ToArrayBuffer(base64)	Base64转ArrayBuffer	ArrayBuffer	二进制数据处理

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 双向转换：支持Base64和PixelMap的双向转换

1.2 转换流程对照

转换方向	源格式	目标格式	典型场景
解码	Base64	PixelMap	网络图片展示
编码	PixelMap	Base64	图片上传/存储
转换	Base64	ArrayBuffer	二进制处理

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 Base64转PixelMap

import { ImageUtil } from '@pura/harmony-utils';

Button('Base64转PixelMap')
  .width('100%')
  .onClick(async () => {
    try {
      let base64Str = '...'; // Base64编码的图片字符串
      let pixelMap = await ImageUtil.base64ToPixelMap(base64Str);
      this.result = `转换成功 ✅\nPixelMap尺寸: ${pixelMap.getImageInfo().size}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 PixelMap转Base64

Button('PixelMap转Base64')
  .width('100%')
  .onClick(async () => {
    try {
      let base64 = await ImageUtil.pixelMapToBase64(this.pixelMap);
      this.result = `转换成功 ✅\nBase64长度: ${base64.length}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { ImageUtil } from '@pura/harmony-utils';

@Entry
@Component
struct ImageConvertDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('Base64转PixelMap').width('100%').onClick(async () => {
        try {
          this.result = 'Base64与PixelMap互转\n适用于图片上传和缓存';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 图片上传封装

import { ImageUtil } from '@pura/harmony-utils';

async function uploadImage(pixelMap: PixelMap): Promise<void> {
  let base64 = await ImageUtil.pixelMapToBase64(pixelMap);
  let response = await fetch('https://api.example.com/upload', {
    method: 'POST',
    body: JSON.stringify({ image: base64 })
  });
  return response.json();
}

4.2 图片缓存管理

async function cacheImage(pixelMap: PixelMap, key: string): Promise<void> {
  let base64 = await ImageUtil.pixelMapToBase64(pixelMap);
  PreferencesUtil.putString(key, base64);
}

async function getCachedImage(key: string): Promise<PixelMap | null> {
  let base64 = PreferencesUtil.getString(key, '');
  if (base64) {
    return await ImageUtil.base64ToPixelMap(base64);
  }
  return null;
}

五、注意事项

1. Base64格式：需确保Base64字符串包含正确的数据前缀
2. 内存占用：Base64编码比原始数据大约33%
3. 异步操作：转换方法为异步，需使用await
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 大图片：大图片转换可能耗时，建议在子线程处理

六、常见问题

Q1: Base64转PixelMap失败？

检查Base64字符串是否完整，是否包含正确的MIME类型前缀。

Q2: 转换后图片模糊？

可能是Base64编码时质量损失，建议使用无损格式（如PNG）。

Q3: Base64字符串太长怎么办？

可以先压缩图片再转Base64，或使用文件上传替代Base64传输。

Q4: 如何判断Base64是否为有效图片？

检查Base64前缀是否包含 data:image/ 标识。

总结

ImageUtil 的Base64与PixelMap互转方法为图片处理提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据场景选择合适的转换方向。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。