# zip

Zip模块管理文件压缩和解压，通过plus.zip可获取压缩管理对象。

## 方法：

- compress: 压缩生成Zip文件
- decompress: 解压缩Zip文件
- compressImage: 图片压缩转换

## 对象：

- CompressImageOptions: JSON对象，配置图片压缩转换的参数
- ClipImageOptions: JSON对象，图片裁剪区域的参数

## 回调方法：

- CompressImageSuccessCallback: 图片压缩转换操作成功回调接口
- ZipSuccessCallback: 操作成功回调函数接口，在解压Zip文件或压缩成Zip文件成功时调用
- ZipErrorCallback: 操作错误回调函数接口，在解压Zip文件或压缩成Zip文件失败时调用

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Zip": {
    		"description": "压缩与解压"
    	}
    }
    }

# CompressImageOptions

JSON对象，配置图片压缩转换的参数

## 说明：

设置width/height属性则表示需对图片进行缩放转换操作； 设置rotate属性则表示需对图片进行旋转转换操作； 设置clip属性则表示需对图片进行裁剪转换操作； 如同时设置了多个转换操作，则按缩放、旋转、裁剪顺序进行操作。

## 属性：

- src: (String 类型 )压缩转换原始图片的路径

  支持以下图片路径： 相对路径 - 相对于当前页面的host位置，如"a.jpg"，注意当前页面为网络地址则不支持； 绝对路径 - 系统绝对路径，如Android平台"/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/www/ａ.jpg"，iOS平台"/var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/www/a.png"； 相对路径URL(RelativeURL) - 以"_"开头的相对路径，如"_www/a.jpg"、"_doc/b.jpg"、"_documents/c.jpg"、"_downloads/d.jpg"； 本地路径URL - 以“file://”开头，后面跟随系统绝对路径。

- dst: (String 类型 )压缩转换目标图片的路径

  支持以下图片路径： 绝对路径 - 系统绝对路径，如Android平台"/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc/ａ.jpg"，iOS平台"/var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/doc/a.png"； 相对路径URL(RelativeURL) - 以"_"开头的相对路径，如"_doc/b.jpg"、"_documents/c.jpg"、"_downloads/d.jpg"，注意不支持"_www"开头的路径； 本地路径URL - 以“file://”开头，后面跟随系统绝对路径。 注意：如果设置的路径无权限访问，则返回失败。

- overwrite: (Boolean 类型 )覆盖生成新文件

  仅在dst制定的路径文件存在时有效： true表示覆盖存在的文件； false表示不覆盖，如果文件存在，则返回失败。 默认值为false。

- format: (String 类型 )压缩转换后的图片格式

  支持"jpg"、"png",如果未指定则使用源图片的格式。

- quality: (Number 类型 )压缩图片的质量

  取值范围为1-100，1表示使用最低的图片质量（转换后的图片文件最小）、100表示使用最高的图片质量（转换后的图片文件最大）； 默认值为50。

- width: (String 类型 )缩放图片的宽度

  支持像素值（如"100px"）、百分比（如"50%"）、自动计算（如"auto"，即根据height与源图高的缩放比例计算，若未设置height则使用源图高度）； 默认值为"auto"。 注意：若设置了width属性值不合法（如"0px"），则不对图片进行缩放操作。

- height: (String 类型 )缩放图片的高度

  支持像素值（如"100px"）、百分比（如"50%"）、自动计算（如"auto"，即根据width与源图宽的缩放比例计算，若未设置width则使用源图高度）； 默认值为"auto"。 注意：若设置了height属性值不合法（如"0px"），则不对图片进行缩放操作。

- rotate: (Number 类型 )旋转图片的角度

  支持值：90-表示旋转90度；180-表示旋转180度；270-表示旋转270度。 注意：若设置rotate属性值不合法，则不对图片进行旋转操作。

- clip: (ClipImageOptions 类型 )裁剪图片的区域

  值参考ClipImageOptions定义，若设置clip属性值不合法，则不对图片进行裁剪操作。

# ClipImageOptions

JSON对象，图片裁剪区域的参数

## 属性：

- top: (String 类型 )图片裁剪区域与原图片上边界的偏移距离

  支持像素值（如"10px"）、百分比（如"10%"）；默认值为"0px"。 注意：如果top值超出原图片高度，则图片裁剪失败。

- left: (Stirng 类型 )图片裁剪区域与原图片左边界的偏移距离

  支持像素值（如"10px"）、百分比（如"10%"）；默认值为"0px"。 注意：如果left值超出原图片宽度，则图片裁剪失败。

- width: (String 类型 )图片裁剪区域的宽度

  支持像素值（如"100px"）、百分比（如"50%"）、自动计算（如"auto"，即从left位置到图片右边界的宽度）；默认值为"auto"。 注意：如果left值加width值超出原图片宽度，则使用"auto"值进行裁剪。

- height: (String 类型 )图片裁剪区域的高度

  支持像素值（如"100px"）、百分比（如"50%"）、自动计算（如"auto"，即从top位置到图片下边界的高度）；默认值为"auto"。 注意：如果top值加height值超出原图片高度，则使用"auto"值进行裁剪。

# CompressImageSuccessCallback

图片压缩转换操作成功回调接口

    void onSuccess( Event event ){
    	// Code here
    	var target = event.target; // 压缩转换后的图片url路径，以"file://"开头
    	var size = event.size; // 压缩转换后图片的大小，单位为字节（Byte）
    	var width = event.width; // 压缩转换后图片的实际宽度，单位为px
    	var height = event.height; // 压缩转换后图片的实际高度，单位为px
    }

## 参数：

- event: ( Event ) 可选 图片压缩转换后的图片信息
  可通过event.target（String类型）获取压缩转换后的图片url路径，以"file://"开头，可直接在html页面中通过src属性引用，如Android平台"file:///storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc/ａ.jpg"，iOS平台"file:///var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/doc/a.png"； 可通过event.size（Number类型）获取压缩转换后图片的大小，单位为字节（Byte）； 可通过event.width（Number类型）获取压缩转换后的图片的实际宽度，单位为px； 可通过event.height（Number类型）获取压缩转换后的图片的实际高度，单位为px。

## 返回值：

void : 无

# ZipSuccessCallback

操作成功回调函数接口，在解压Zip文件或压缩成Zip文件成功时调用

    void onSuccess(){
    	// Code here
    }

## 参数：

无

## 返回值：

void : 无

# ZipErrorCallback

操作错误回调函数接口，在解压Zip文件或压缩成Zip文件失败时调用

    void onError(error){
    	// Handle the error
    	var code = error.code; // 错误编码
    	var message = error.message; // 错误描述信息
    }

## 参数：

- error: ( Exception ) 可选 Zip操作的错误信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。

## 返回值：

void : 无