鸿蒙三方库 | harmony-utils之ImageUtil图片保存到本地详解

前言

将应用中的图片保存到本地相册是常见的用户需求，如保存截图、下载图片等。@pura/harmony-utils 的 ImageUtil 封装了图片保存方法，支持保存PixelMap到系统相册。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ImageUtil保存核心API

ImageUtil 提供了以下图片保存方法：

方法	说明	返回类型	使用场景
`savePixelMap(pixelMap)`	保存PixelMap到相册	string	截图保存
`saveImageToArrayBuffer(path)`	图片转ArrayBuffer	ArrayBuffer	图片处理

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
相册集成：保存后可在系统相册中查看

1.2 保存方式对照

方式	方法	保存位置	可见性
相册保存	savePixelMap	系统相册	所有应用可见
文件保存	writeArrayBufferSync	应用目录	仅本应用可见

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 保存图片到相册

typescript 复制代码

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

Button('保存图片到相册')
  .width('100%')
  .onClick(async () => {
    try {
      let uri = await ImageUtil.savePixelMap(this.pixelMap);
      this.result = `保存成功 ✅\nURI: ${uri}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 保存前确认

typescript 复制代码

async saveWithConfirm() {
  let confirm = await DialogUtil.confirm('是否保存图片到相册？');
  if (confirm) {
    let uri = await ImageUtil.savePixelMap(this.pixelMap);
    ToastUtil.show('保存成功');
  }
}

三、完整页面示例

typescript 复制代码

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

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

  build() {
    Column({ space: 12 }) {
      Button('保存图片').width('100%').onClick(async () => {
        try {
          this.result = '图片保存功能\n需先创建PixelMap对象';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 截图保存

typescript 复制代码

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

async function saveScreenshot(component: Component): Promise<void> {
  let pixelMap = await SnapshotUtil.snapshot(component);
  let uri = await ImageUtil.savePixelMap(pixelMap);
  ToastUtil.showToast('截图已保存到相册');
}

4.2 批量保存

typescript 复制代码

async function saveMultipleImages(pixelMaps: PixelMap[]): Promise<string[]> {
  let uris: string[] = [];
  for (let pixelMap of pixelMaps) {
    let uri = await ImageUtil.savePixelMap(pixelMap);
    uris.push(uri);
  }
  return uris;
}

五、注意事项

权限要求：保存到相册需要相册写入权限
主线程：保存操作需在主线程执行
文件格式：默认保存为PNG格式
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
存储空间：保存前检查存储空间是否充足

六、常见问题

Q1: 保存图片时提示权限不足？

需要在module.json5中配置 ohos.permission.WRITE_IMAGEVIDEO 权限，并动态申请。

Q2: 保存后相册中看不到？

部分设备需要刷新相册索引，可以通知媒体库更新。

Q3: 如何指定保存格式？

当前版本默认PNG格式，如需其他格式需先转换再保存。

Q4: 保存大图片会OOM吗？

大图片保存可能消耗较多内存，建议先压缩再保存。

总结

ImageUtil 的图片保存方法为应用图片导出提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现截图保存、图片下载等功能。

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