前言
ImageSource是HarmonyOS图片解码的入口对象，用于从文件、缓冲区等创建图片数据源。@pura/harmony-utils的ImageUtil封装了ImageSource创建方法，简化了图片数据源的创建流程。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。
一、ImageUtil ImageSource核心API
ImageUtil提供了以下ImageSource创建方法：
| 方法 | 说明 | 返回类型 | 使用场景 |
|---|---|---|---|
createImageSource(path) | 从路径创建ImageSource | ImageSource | 本地图片解码 |
createImageSourceFromBuffer(buffer) | 从缓冲区创建ImageSource | ImageSource | 网络图片解码 |
packToFile(pixelMap, path) | 打包PixelMap到文件 | void | 图片文件保存 |
1.1 核心特性
- 简洁易用：封装复杂API为一行调用，降低使用门槛
- 类型安全：完整的TypeScript类型定义，编译期即可发现错误
- 异常处理：内置异常捕获机制，避免运行时崩溃
- 多源创建：支持从文件路径和缓冲区创建ImageSource
1.2 ImageSource创建方式对照
| 创建方式 | 方法 | 数据来源 | 适用场景 |
|---|---|---|---|
| 文件路径 | createImageSource | 本地文件 | 本地图片加载 |
| 缓冲区 | createImageSourceFromBuffer | 内存数据 | 网络图片解码 |
二、完整使用步骤
2.1 安装依赖
ohpminstall@pura/harmony-utils2.2 从文件创建ImageSource
import{ImageUtil}from'@pura/harmony-utils';Button('从文件创建ImageSource').width('100%').onClick(()=>{try{letpath=FileUtil.getFilesDir()+'/image.jpg';letimageSource=ImageUtil.createImageSource(path);this.result=`ImageSource创建成功 ✅\n路径:${path}`;}catch(e){this.result='异常: '+e;}})2.3 从缓冲区创建ImageSource
Button('从缓冲区创建ImageSource').width('100%').onClick(()=>{try{letbuffer=newArrayBuffer(0);letimageSource=ImageUtil.createImageSourceFromBuffer(buffer);this.result='从缓冲区创建成功 ✅';}catch(e){this.result='异常: '+e;}})三、完整页面示例
import{ImageUtil}from'@pura/harmony-utils';@Entry@Componentstruct ImageSourceDemo{@Stateresult:string='';build(){Column({space:12}){Button('创建ImageSource').width('100%').onClick(()=>{this.result='ImageSource是图片解码入口\n支持从文件和缓冲区创建';});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}四、进阶用法
4.1 图片信息获取
import{ImageUtil}from'@pura/harmony-utils';functiongetImageInfo(path:string):Record<string,Object>{letimageSource=ImageUtil.createImageSource(path);letinfo=imageSource.getImageInfo();return{width:info.size.width,height:info.size.height,mimeType:imageSource.getImageProperty('COMPRESSION_TYPE')};}4.2 多帧图片处理
functiongetFrameCount(path:string):number{letimageSource=ImageUtil.createImageSource(path);returnimageSource.getFrameCount();}五、注意事项
- 文件格式：支持JPEG、PNG、GIF、BMP、WebP等常见格式
- 资源释放：使用完毕后需释放ImageSource资源
- 大图片：大图片创建ImageSource可能耗时
- 初始化依赖：使用前需确保
AppUtil.init()已调用 - 路径有效：确保文件路径存在且可读
六、常见问题
Q1: createImageSource()返回null？
检查文件路径是否正确，文件是否存在，以及是否有读取权限。
Q2: 支持哪些图片格式？
支持JPEG、PNG、GIF、BMP、WebP、HEIF等HarmonyOS支持的图片格式。
Q3: 如何从网络图片创建ImageSource？
先下载图片到本地或获取ArrayBuffer，再使用对应方法创建。
Q4: ImageSource和PixelMap有什么区别？
ImageSource是图片数据源（解码入口），PixelMap是解码后的位图数据（可展示）。
总结
ImageUtil的ImageSource创建方法为图片解码提供了便捷入口。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据数据来源选择合适的创建方式。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。
