前言

图片压缩在上传、分享等场景中非常实用，可以减少传输时间和存储空间。@pura/harmony-utils 的 ImageUtil 封装了图片压缩方法，支持质量压缩和尺寸压缩。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ImageUtil压缩核心API

ImageUtil 提供了以下图片压缩方法：

方法	说明	返回类型	使用场景
compressPixelMap(pixelMap, quality)	质量压缩	ArrayBuffer	减小文件大小
scalePixelMap(pixelMap, scale)	缩放压缩	PixelMap	缩小图片尺寸

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 双模式压缩：支持质量压缩和尺寸压缩两种方式

1.2 压缩方式对照

压缩方式	参数	效果	适用场景
质量压缩	0-100	降低图片质量	JPEG图片上传
缩放压缩	0-1	缩小图片尺寸	缩略图生成

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 质量压缩

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

Button('质量压缩(50%)')
  .width('100%')
  .onClick(async () => {
    try {
      let compressed = await ImageUtil.compressPixelMap(this.pixelMap, 50);
      this.result = `压缩成功 ✅\n质量: 50%\n压缩后大小: ${compressed.byteLength}字节`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 缩放压缩

Button('缩放压缩(50%)')
  .width('100%')
  .onClick(async () => {
    try {
      let scaled = await ImageUtil.scalePixelMap(this.pixelMap, 0.5);
      this.result = `缩放成功 ✅\n缩放比例: 50%`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('质量压缩').width('100%').onClick(() => {
        this.result = '质量压缩: 降低图片质量\n参数0-100，值越小文件越小';
      });
      Button('缩放压缩').width('100%').onClick(() => {
        this.result = '缩放压缩: 缩小图片尺寸\n参数0-1，值越小尺寸越小';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 自适应压缩策略

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

async function smartCompress(pixelMap: PixelMap, maxSizeKB: number): Promise<ArrayBuffer> {
  let quality = 100;
  let result: ArrayBuffer;
  do {
    result = await ImageUtil.compressPixelMap(pixelMap, quality);
    quality -= 10;
  } while (result.byteLength > maxSizeKB * 1024 && quality > 10);
  return result;
}

4.2 缩略图生成

async function generateThumbnail(pixelMap: PixelMap, maxSize: number = 200): Promise<PixelMap> {
  let info = pixelMap.getImageInfo();
  let scale = Math.min(maxSize / info.size.width, maxSize / info.size.height);
  if (scale >= 1) return pixelMap;
  return await ImageUtil.scalePixelMap(pixelMap, scale);
}

五、注意事项

1. 质量参数：质量压缩参数0-100，值越小文件越小
2. 缩放比例：缩放压缩参数0-1，值越小尺寸越小
3. 格式影响：质量压缩对JPEG有效，PNG无损格式效果有限
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 异步操作：压缩方法为异步，需使用await

六、常见问题

Q1: 质量压缩后图片变模糊？

质量参数设置过低会导致图片模糊，建议不低于50。

Q2: PNG图片质量压缩效果不明显？

PNG是无损格式，质量压缩主要对JPEG有效。PNG图片建议使用缩放压缩。

Q3: 如何在压缩率和清晰度之间平衡？

建议先缩放到合适尺寸，再进行质量压缩，通常质量60-80之间效果较好。

Q4: 压缩后如何获取文件大小？

质量压缩返回ArrayBuffer，通过 buffer.byteLength 获取字节数。

总结

ImageUtil 的图片压缩方法为图片优化提供了双模式支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据场景选择质量压缩或缩放压缩。

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