# ImageUtilProject

**Repository Path**: zhongrui_developer/ImageUtilProject

## Basic Information

- **Project Name**: ImageUtilProject
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-12
- **Last Updated**: 2025-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: HarmonyOS组件, harmony

## README

# hm_image

## 简介

图片压缩方案，支持的数据类型：fd，uri，图片沙箱路径，图片网络地址，base64图片，ArrayBuffer。  
支持批量压缩，提供压缩进度监听。

#### 额外提供

1：fd转ArrayBuffer、UintArray方法  
2：uri转ArrayBuffer、UintArray方法  
3：沙箱路径转ArrayBuffer、UintArray方法  
4：ArrayBuffer转UintArray方法

## 下载安装

```text
ohpm install @zhongrui/hm_image
```

#### 导入模块

```typescript
import { HMImage, CompressImageOption, CompressResult } from "@zhongrui/hm_image";
```

##### 图片压缩

```typescript
public compress(context:Context){
  // 此处换成实际的图片uri
  const imageData = 'file://com.example.xxx/xxx.jpg'
  // 支持fd、uri、沙箱路径、图片url、base64图片、ArrayBuffer数据
  HMImage.compress(context)
    // 打开调试模式，输出日志
    .setDebug(true)
    .setProgressListener((progress:number,total:number)=>{
      //压缩进度，progress：压缩成功的数量，total：总数量
    })
    .start([imageData]).then((result: CompressResult) => {
    // 本次压缩是否全部成功
    const isAllSuccess = result.isAllSuccess
    // 本次压缩成功的数据
    const successData = result.successData
    // 本次压缩失败的数据
    const failData = result.failData
    // 处理完业务操作之后，调用delete()方法可以删除本次压缩保存的沙箱图片
    result.delete()
    // 处理完业务操作之后，调用deleteAll()方法可以删除所有压缩保存在沙箱目录的图片，效果和HMImage.deleteAllCompressImage(context)一致
    result.deleteAll()
  }).catch((error: BusinessError) => {
    const code = error.code
    const message = error.message
    console.info("compress err code:" + code + ",message:" + message)
  })
}
```

##### compress
compress(context: Context, option?: CompressImageOption)  
设置压缩参数

| 参数名     | 类型                  | 是否必填 | 说明     |
|---------|---------------------|------|--------|
| context | Context             | 是    | 应用上下文  |
| option  | CompressImageOption | 否    | 图片压缩选项 |

CompressImageOption

| 参数名            | 类型                     | 是否必填 | 说明                                                         |
|----------------|------------------------|------|------------------------------------------------------------|
| maxWidth       | number                 | 否    | 限制图片压缩后的最大宽度不超过maxWidth，单位：px                              |
| maxHeight      | number                 | 否    | 限制图片压缩后的最大高度不超过maxHeight，单位：px                             |
| scale          | number                 | 否    | 图片压缩时设置的分辨率缩放比例取值范围：(0,1]                                  |
| maxFileSize    | number                 | 否    | 设置图片压缩后的文件大小不超过maxFileSize,单位：byte                         |
| ignoreFileSize | number                 | 否    | 图片大小如果小于等于ignoreFileSize，则不压缩，单位：byte                      |
| targetDir      | string                 | 否    | 设置图片保存的目录                                                  |
| quality        | number                 | 否    | 图片压缩的质量，取值范围：(0,100]，默认值：70                                |
| qualityStep    | number                 | 否    | 如果图片压缩后的文件大小超过maxFileSize，quality会依次减少qualityStep再进行压缩     |
| compressNum    | number                 | 否    | 同时压缩图片的多线程数量，默认值：8                                         |
| imageFormat    | CompressionImageFormat | 否    | 取值：JPEG，WEBP，PNG，HEIC，HEIF，默认值：CompressionImageFormat.WEBP |

##### start

start(image: ImageDataType[]): Promise< CompressResult >;  
参数：

| 参数名   | 类型              | 是否必填 | 说明                                                           |
|-------|-----------------|------|--------------------------------------------------------------|
| image | ImageDataType[] | 是    | 图片数据,支持string或number或ArrayBuffer类型，可以是fd,uri,url,沙箱路径，base64 |

返回值：

| 参数名          | 类型                  | 说明            | 
|--------------|---------------------|---------------|
| isAllSuccess | boolean             | 图片是否全部压缩成功    |
| successData  | CompressImageData[] | 压缩成功的图片数据     |
| failData     | CompressImageData[] | 压缩失败的图片数据     |
| delete       | function            | 删除本次图片压缩文件的方法 |
| deleteAll    | function            | 删除所有图片压缩文件的方法 |

CompressImageData

| 参数名              | 类型            | 说明                 | 
|------------------|---------------|--------------------|
| code             | number        | 错误码                |
| message          | string        | 错误提示信息             |
| origin           | ImageDataType | 原始图片数据             |
| originSize       | number        | 原始图片文件大小，单位：byte   |
| fileName         | string        | 原始图片缓存到沙箱目录的文件名    |
| filePath         | string        | 原始图片缓存到沙箱目录的文件路径   |
| compressFileName | string        | 压缩后的图片文件名          |
| compressFilePath | string        | 压缩后的图片文件路径         |
| compressFileSize | number        | 压缩后的图片文件大小，单位：byte |

CompressImageData.code错误码

| 错误码  | 说明              |
|------|-----------------|
| 1    | 成功              |
| -1   | 内部错误            |
| 1001 | 参数错误            |
| 1002 | 原始图片复制到沙箱目录错误   |
| 1003 | 检查图片大小错误        |
| 1005 | 剩余空间不足          |
| 1006 | 创建imageSource失败 |
| 1007 | 分辨率压缩失败         |
| 1008 | 质量压缩失败          |
| 1009 | 保存和压缩过程错误       |
| 1010 | 网络图片地址为空        |
| 1011 | 获取网络图片大小错误      |
| 1012 | 下载网络地址错误        |

注意：start().then().catch((error: BusinessError) => {})中的BusinessError错误码需要另行处理,可参考官方文档

##### deleteAllCompressImage

删除所有图片压缩保存到本地的文件的方法

```typescript
// 删除所有压缩保存在沙箱目录的图片
HMImage.deleteAllCompressImage(context)

let targetDir='/data/xxxx/haps/entry/files'
// 如果压缩图片时CompressImageOption参数有设置targetDir，这里可以传入otherDir一起删除
HMImage.deleteAllCompressImage(context,targetDir)
  
let otherDir=['/data/xxxx/haps/entry/files','/data/xxxx/haps/entry/cache']
// 除了删除默认缓存目录，还需要删除其他多个目录
HMImage.deleteAllCompressImage(context,...otherDir)
```

参数：

| 参数名     | 类型          | 是否必传 | 说明    | 
|---------|-------------|------|-------|
| context | Context     | 是    | 应用上下文 |
| dirPath | ...string[] | 否    | 其他目录  |  


#### HMImageUtils
```typescript
// fd、uri、沙箱路径文件转ArrayBuffer
HMImageUtils.fileToArrayBuffer(file: number | string)

// base64数据转ArrayBuffer
HMImageUtils.base64ToArrayBuffer(base64Image: string)

// fd、uri、沙箱路径、base64、ArrayBuffer数据转Uint8Array
HMImageUtils.fileToUint8Array(file: ImageDataType)
```

#### 开源协议

本项目基于 [MIT license](https://gitee.com/zhongrui_developer/ImageUtilProject/blob/master/LICENSE) ，请自由地享受和参与开源。