压缩与解压 - Zip
# Zip
> Stability: 2 - Stable
Zip模块用于处理文件的压缩和解压，并支持加密压缩。
> zip功能来自[zip4j](https://javadoc.io/doc/net.lingala.zip4j/zip4j/1.3.2/net/lingala/zip4j/model/ZipParameters.html)，可阅读相关文档获取更多信息。
## $zip.zipDir(dir, dest[, options])
* `dir` {string} 需要压缩的文件夹路径，如果文件夹下有子文件夹均会一并压缩
* `dest` {string} 压缩后的压缩包存放路径
* `options` {object} 可选参数，选项option包括以下内容，完整的选项参见[压缩选项](#压缩选项)：
* `password` {string} 加密压缩的密码。如果设置密码但不设置加密方法，则加密方法默认为AES
* `compressionMethod` {string} 压缩方式，`COMP_STORE`为仅打包不压缩, `COMP_DEFLATE`为压缩（默认）
* `encryptionMethod` {string} 加密方法，`ENC_NO_ENCRYPTION`为不加密(默认)，`ENC_METHOD_STANDARD`为标准机密, `ENC_METHOD_AES`为AES加密
* `compressionLevel` {number} 压缩级别，0~9，0为不压缩，9为最好压缩（速度较慢）。在8.7以前版本，默认为0不压缩；在8.7以后，该值默认为5（正常压缩）
* `aesKeyStrength` {string} AES加密强度，包括`AES_STRENGTH_128`，`AES_STRENGTH_192`，`AES_STRENGTH_256`
* `readHiddenFiles` {boolean} 压缩文件夹时是否包含隐藏文件。如果为true，则在将文件夹添加到zip时将包含隐藏文件
* `includeRootFolder` {boolean} 设置标志以指示添加文件的父文件夹是否将包含在ZIP中。如果为true，则添加文件的父文件夹将包含在ZIP中。默认true
* `rootFolderInZip` {string} 设置压缩包首目录的文件夹名称，如果没有首目录，则创建这个首目录
压缩文件夹下所有文件/文件夹，生成到目标路径`dest`。
一个简单的压缩文件夹例子。
```javascript
// 需压缩文件路径
let dir = "./zipExample2/";
// 压缩后文件存放路径
if (!$files.exists(dir)) {
// 文件夹不存在 创建文件夹
$files.create(dir);
}
// 创建一个文件，自己可多放几个文件或文件夹运行看效果
$files.create($files.join(dir, "test.js"));
// 压缩后文件存放路径
let zipFile = $files.join(dir, "未加密压缩.zip");
// 删除同名文件
$files.remove(zipFile);
// 压缩
$zip.zipDir(dir, zipFile);
log("压缩完成，压缩包路径：" + zipFile);
```
加密压缩例子
```javascript
// 需压缩文件路径
let dir = "./zipExample2/";
// 压缩后文件存放路径
if (!$files.exists(dir)) {
// 文件夹不存在 创建文件夹
$files.create(dir);
}
// 创建一个文件，自己可多放几个文件或文件夹运行看效果
$files.create($files.join(dir, "test.js"));
// 压缩包存放路径
let encryptedZipFile = $files.join(dir, "加密压缩.zip");
$files.remove(encryptedZipFile); // 删除同名文件
// 压缩
$zip.zipDir(dir, encryptedZipFile, {
password: "Auto.js Pro" // 压缩密码
compressionLevel: 5, // 压缩级别
aesKeyStrength: 'AES_STRENGTH_256', // 加密方法
readHiddenFiles: false, // 隐藏文件不添加进压缩包
includeRootFolder: false, //不添加文件夹父目录进压缩包
rootFolderInZip: "测试" // 为压缩包添加一个父目录
});
log("加密压缩完成，压缩包路径：" + encryptedZipFile);
```
## $zip.zipFile(file, dest[, options])
* `file` {string} 需要压缩的单文件路径。
* `dest` {string} 压缩后的压缩包存放路径
* `options` {object} 选项参见参见[压缩选项](#压缩选项)
压缩单文件`file`到路径`dest`。
```javascript
let path = "./zipExample/test.js";
if (!$files.exists(path)) {
$files.create(path);
}
let zipFilePath = "./zipExample/test.zip";
$zip.zipFile(path, zipFilePath);
log("单文件压缩完成，压缩包路径：" + zipFilePath);
```
## $zip.zipFiles(fileList, dest[, options])
* `fileList` {Array<string>} 需压缩的多个文件路径的数组
* `dest` {string} 压缩目标路径
* `options` {object} 选项参见[压缩选项](#压缩选项)
压缩多个文件`fileList`到路径`dest`。`fileList`中不能包含文件夹。
```javascript
let dir = "./zipExample3/";
if (!$files.exists(dir)) {
$files.create(dir);
}
let fileList = ["file1.js", "file2.js", "file3.js"].map(p => $files.join(dir, p));
fileList.forEach(file => {
$files.create(file);
});
let zipMultiFile = $files.join(dir, "多文件压缩.zip");
$files.remove(zipMultiFile); // 删除同名文件
$zip.zipFiles(fileList, zipMultiFile); // 压缩
log("多文件压缩完成，压缩包路径：" + zipMultiFile);
```
## $zip.unzip(zipFile, dest[, options])
* `zipFile` {string} 需解压的压缩包文件路径
* `dest` {string} 解压后的文件夹目录
* `options` {object} 解压选项，可选，参见[解压选项](#解压选项)
解压zip文件。如果文件夹`dest`不存在则创建该文件夹并将内容解压到里面；如果`dest`已经存在，则在`dest`下面创建一个和`zipFile`文件同名的文件夹，并将内容解压到里面。
```javascript
// 准备一个加密的压缩包
let dir = "./zipExample2/";
if (!$files.exists(dir)) {
$files.create(dir);
}
// 压缩后文件存放路径
let encryptedZipFile = $files.join(dir, "加密压缩.zip");
$files.remove(encryptedZipFile); // 删除同名文件
// 压缩
$zip.zipDir(dir, encryptedZipFile, {
password: "Auto.js Pro" // 压缩密码
});
$zip.unzip(encryptedZipFile, './zipExample5', {
password: 'Auto.js Pro' // 解压密码
});
log("加密zip解压成功，解压路径：" + "./zipExample5/");
```
## $zip.open(file)
* `file` {string} 压缩包文件路径
* 返回 {[ZipFile](#zipfile)} ZipFile对象
打开一个zip文件，返回`ZipFile`对象，可对该对象进行进一步的zip操作。
# ZipFile
`$zip.open()`返回的对象，用于在压缩包中增删文件、获取文件头信息、解压等。
## ZipFile.getPath()
* 返回 {string} 返回路径
获取当前压缩包的路径。
```javascript
let path = "./test.zip";
let zipFile = $zip.open(path);
log(zipFile.getPath();
// 输出路径 "./test.zip"
```
## ZipFile.isValidZipFile()
* 返回 {boolean} 是否是有效压缩包
获取当前压缩包是否是一个有效的压缩包。
如果选择的路径不是一个压缩包或该文件不存在，均返回`false`。
## ZipFile.setPassword(password)
* `password` {string} 设置密码
如果文件是一个加密的压缩包，必须用此函数设置正确的解压密码，才能解压出加密的文件。
未设置密码尝试解压加密的压缩包将抛出异常，选择的压缩包文件不存在使用本函数将抛出`ZipException`。
## ZipFile.isEncrypted()
* 返回 {boolean} 是否压缩包加密
获取当前压缩包是否是加密压缩包。
## ZipFile.addFile(file[, options])
* `file` {string} 本地文件路径
* `options` {object} 压缩选项，可选，参见[压缩选项](#压缩选项)
在压缩包中添加指定文件。
```javascript
let zipFile = $zip.open("./app.apk");
zipFile.addFile(file);
```
## ZipFile.addFiles(fileList, options)
* `fileList` {Array<string>} 要添加的本地文件路径的数组
* `options` {object} 压缩选项，可选，参见[压缩选项](#压缩选项)
在压缩包中添加多个文件。
## ZipFile.addFolder(folder[, options])
* `folder` {string} 文件夹路径
* `options` {object} 压缩选项，可选，参见[压缩选项](#压缩选项)
在压缩包中添加指定文件夹。
> 注意不要添加压缩包的父目录，否则可能造成循环无限添加！
一个备份脚本的简单例子：
```javascript
let zipFile = "/sdcard/scripts.zip";
//指定压缩包文件
let zip = $zip.open(zipFile);
log("开始备份，取决与你的脚本数量");
// 向压缩包添加当前文件夹
zip.addFolder("./");
log("备份完成，压缩包路径为：" + zipFile);
```
## ZipFile.removeFile(file)
* `file` {string} 要删除的文件
删除zip文件内的指定文件。此方法首先找到文件头，然后删除文件；如果文件不存在，则此方法引发异常。
如果zip文件是分割后的zip文件，则此方法会抛出异常，原因是zip规范不允许更新拆分的zip档案。
```javascript
let zipFile = $zip.open("./app.apk");
zipFile.removeFile("res/drawable/logo.png");
```
## ZipFile.extractFile(file, dest[, options, newFileName])
* `file` {string} 要解压的文件
* `dest` {string} 解压文件的目标路径
* `options` {Object} 解压选项，可选。参见[解压选项](#解压选项)
* `newFileName` {string} 解压后文件的新名字，可选.
从压缩包文件中提取特定文件到目标路径。如果目标路径无效，则此方法将引发异常。
## ZipFile.extractAll(dest{, options})
* `dest` {string} 解压路径
* `options` {Object} 解压选项，可选。参见[解压选项](#解压选项)
解压所有文件到目标路径`dest`。
```javascript
let zip = $zip.open("./test.zip");
zip.addFiles(["./test.js", "./test.txt"]);
zip.extractAll("./test");
```
## ZipFile.getFileHeader(file)
* `file` {string} 压缩包内指定文件路径
* 返回 {[FileHeader](https://javadoc.io/doc/net.lingala.zip4j/zip4j/1.3.2/net/lingala/zip4j/model/FileHeader.html)}
获取压缩包内指定文件的文件头信息。文件头信息包括校验值，是否加密，注释等。
## ZipFile.getFileHeaders()
* 返回 {Array<[FileHeader](https://javadoc.io/doc/net.lingala.zip4j/zip4j/1.3.2/net/lingala/zip4j/model/FileHeader.html)>}
获取压缩包内所有文件的文件头信息。文件头信息包括校验值，是否加密，注释等。
# 压缩选项
`options` {object} 包括:
* `aesKeyStrength` {string} AES加密强度，包括`AES_STRENGTH_128`，`AES_STRENGTH_192`，`AES_STRENGTH_256`
* `compressionLevel` {number} 压缩级别，0~9，0为不压缩，9为最好压缩（速度较慢）。在8.7以前版本，默认为0不压缩；在8.7以后，该值默认为5（正常压缩）
* `compressionMethod` {string} 压缩方式，`COMP_STORE`为仅打包不压缩, `COMP_DEFLATE`为压缩（默认）
* `defaultFolderPath` {string} 压缩或添加文件时，指定文件在压缩包的默认文件夹位置
* `encryptionMethod` {string} 加密方法，`ENC_NO_ENCRYPTION`为不加密(默认)，`ENC_METHOD_STANDARD`为标准机密, `ENC_METHOD_AES`为AES加密
* `fileNameInZip` {string} 压缩或添加文件时，指定文件在压缩包中的路径、名称
* `includeRootFolder` {boolean} 设置标志以指示添加文件的父文件夹是否将包含在ZIP中。如果为true，则添加文件的父文件夹将包含在ZIP中。默认true
* `password` {string} 加密压缩的密码。如果设置密码但不设置加密方法，则加密方法默认为AES
* `readHiddenFiles` {boolean} 压缩文件夹时是否包含隐藏文件。如果为true，则在将文件夹添加到zip时将包含隐藏文件
* `rootFolderInZip` {string} 设置压缩包首目录的文件夹名称，如果没有首目录，则创建这个首目录
# 解压选项
`options` {object} 包括：
* `ignoreAttribute` {Array<string>} 解压文件写入磁盘时，要忽略的文件属性，包括：
* `alls` 所有属性
* `archive` 压缩包属性
* `dateTime` 时间
* `hidden` 是否隐藏
* `readOnly` 是否只读
* `system` 是否为系统文件