{"_id":"@cordova-ohos/cordova-plugin-zip","_rev":"3-161e311ae9941a5138a35f0a27ddea32","name":"@cordova-ohos/cordova-plugin-zip","dist-tags":{"latest":"3.1.1"},"versions":{"3.1.0":{"name":"@cordova-ohos/cordova-plugin-zip","version":"3.1.0","keywords":["cordova","zip","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-zip@3.1.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-zip/issues"},"dist":{"shasum":"bb51d3ad3b713a8505ce88aae9633299607a0dc6","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-zip/-/cordova-plugin-zip-3.1.0.tgz","fileCount":15,"integrity":"sha512-3rlKRZZzZmKX1pH4XjxD83jbP1xZlN3L8bxNAEqHSIUzhxt1/Fm99oXEkrazHW9KCEAeyXmXPrF6+04uxMFYBw==","signatures":[{"sig":"MEUCIQDsIVrOrkyCuvaT3Z739iiVX2YxDcezfvZzgeJVmDpQnQIgJ1DuuDwEYGEb58AFkkeH6xXx/LbqX3+qHtt+ciKy7po=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":226689},"cordova":{"id":"cordova-plugin-zip","platforms":["ohos"]},"engines":{"cordovaDependencies":{"3.1.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"9efc703fb2a4291ebf89ffcfcf815e305fafec1e","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-zip","type":"git"},"_npmVersion":"10.5.1","description":"Cordova zip Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-zip_3.1.0_1774228744880_0.5022208375285493","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@cordova-ohos/cordova-plugin-zip","version":"3.1.1","description":"Cordova Zip Plugin","cordova":{"id":"cordova-plugin-zip","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-zip"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-zip/issues"},"keywords":["cordova","zip","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"3.1.1":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-zip@3.1.1","gitHead":"f9ab96f2ba79a346f2268ba50eba331990087811","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-sC6ImtfwgTmNmgR3X0WCnpyb1VVP3+V77bqvnh/DL0mHFWJ1VGr+cGQ97hGMztAZADMCU7TLTxHgVU7wGN/fpw==","shasum":"c23c8b4a5b3d0e7903e0a2caa12516de7fe9a4ed","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-zip/-/cordova-plugin-zip-3.1.1.tgz","fileCount":16,"unpackedSize":270011,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD0vre8Nxh+n1EF56ZfhGn1HfoWUb8T48XrgIIr5FYBDAIgJHzO3xJuWgzG8rfc5JuO2usYi00CoYk8vDSs8+q+eBs="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-zip_3.1.1_1785153776984_0.20641143299719555"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T01:19:04.822Z","modified":"2026-07-27T12:02:57.380Z","3.1.0":"2026-03-23T01:19:05.021Z","3.1.1":"2026-07-27T12:02:57.153Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-zip/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","zip","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-zip"},"description":"Cordova Zip Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-zip</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-zip@3.1.0](https://www.npmjs.com/package/cordova-plugin-zip/v/3.1.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-zip](#cordova-plugin-zip)\r\n  - [简介](#简介)\r\n  - [功能特性](#功能特性)\r\n  - [OHOS 平台特性](#ohos-平台特性)\r\n  - [支持平台](#支持平台)\r\n  - [前置准备](#前置准备)\r\n  - [下载安装](#下载安装)\r\n    - [前提条件](#前提条件)\r\n    - [基础安装（推荐，从 npm 仓库）](#基础安装推荐从-npm-仓库)\r\n    - [从 GitCode 安装开发版](#从-gitcode-安装开发版)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载插件](#卸载插件)\r\n  - [OHOS 配置](#ohos-配置)\r\n    - [1. 路径配置说明](#1-路径配置说明)\r\n    - [2. 加密配置说明](#2-加密配置说明)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [1. 基础解压 ZIP 文件（沙箱内文件）](#1-基础解压-zip-文件沙箱内文件)\r\n    - [2. 下载并解压 ZIP 文件（完整场景）](#2-下载并解压-zip-文件完整场景)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心 API 说明](#1-核心-api-说明)\r\n      - [1.1 解压 ZIP 文件（核心 API）](#11-解压-zip-文件核心-api)\r\n    - [2. 常见问题（FAQ）](#2-常见问题faq)\r\n      - [Q1: 调用解压 API 后返回 -1（解压失败）怎么办？](#q1-调用解压-api-后返回--1解压失败怎么办)\r\n      - [Q2: 中文文件名解压后乱码怎么办？](#q2-中文文件名解压后乱码怎么办)\r\n      - [Q3: 进度监听无反应或进度不更新怎么办？](#q3-进度监听无反应或进度不更新怎么办)\r\n      - [Q4: 解压大文件时出现超时或卡顿怎么办？](#q4-解压大文件时出现超时或卡顿怎么办)\r\n      - [Q5: 卸载插件后，沙箱内的压缩解压文件会被删除吗？](#q5-卸载插件后沙箱内的压缩解压文件会被删除吗)\r\n    - [3. 注意事项](#3-注意事项)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\ncordova-plugin-zip 是一款轻量高效的 Cordova 压缩解压插件，基于 ZLib 库开发，支持 ZIP 格式文件的创建、解压及进度监听，适配 Android、iOS、OHOS 三平台，为混合式移动应用提供便捷的文件压缩解压解决方案，适用于资源打包、文件传输优化等场景。本文档仅介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项，帮助开发者快速集成压缩解压功能，重点突出 OHOS 平台的特性与使用规范。\r\n\r\n## 功能特性\r\n\r\n- **多平台兼容**：适配 Android、iOS、OHOS 三平台，重点适配 OHOS 5.0+ 系统，遵循 OHOS 系统文件操作规范，确保功能稳定运行\r\n\r\n- **强大压缩功能**：支持单个文件、多个文件或整个目录的 ZIP 压缩，可自定义压缩级别（从无压缩到最高压缩），满足不同场景需求\r\n\r\n- **高效解压功能**：支持 ZIP 格式文件解压到指定目录，兼容传统加密 ZIP 文件，解压速度快，资源占用低\r\n\r\n- **实时进度监听**：提供压缩/解压进度回调，实时返回处理进度百分比，便于开发者在应用中展示进度条，提升用户体验\r\n\r\n- **多编码支持**：支持 UTF-8 等多种编码格式，有效解决中文文件名乱码问题，适配 OHOS 系统中文环境\r\n\r\n- **轻量高效**：基于 ZLib 原生库开发，插件体积小巧，压缩解压速度优于同类插件，不影响应用整体运行性能\r\n\r\n- **完善错误处理**：具备完善的错误处理机制，返回详细错误信息（如文件不存在、权限不足、加密不兼容等），便于开发者快速定位问题\r\n\r\n- **沙箱适配**：适配 OHOS 系统沙箱机制，支持沙箱路径下的文件压缩解压，符合 OHOS 系统文件访问规范\r\n\r\n## OHOS 平台特性\r\n\r\n该插件在 OHOS 平台的实现贴合系统原生文件操作规范，核心特性及特殊限制如下，需重点关注：\r\n\r\n- 适配 OHOS 沙箱机制：所有压缩解压操作均需在应用沙箱路径下进行，无法访问沙箱外的文件，确保系统安全性\r\n\r\n- 权限依赖：需申请文件访问权限，否则无法读取或写入沙箱内文件，导致压缩解压失败\r\n\r\n- 加密兼容：仅支持 ZIP 传统加密格式，不支持 AES 等高级加密格式，解密失败会返回明确错误信息\r\n\r\n- 路径规范：OHOS 平台需使用沙箱路径（如 cordova.file.externalDataDirectory），否则会导致文件无法访问\r\n\r\n- 进度回调稳定：进度监听回调实时性强，可精准获取压缩解压进度，适配 OHOS 系统异步操作机制\r\n\r\n- 编码优化：针对 OHOS 系统中文环境，默认启用 UTF-8 编码，彻底解决中文文件名乱码问题\r\n\r\n## 支持平台\r\n\r\n- **OHOS**（5.0+，适配系统沙箱机制，支持压缩解压、进度监听，需申请文件访问权限）\r\n\r\n- **Android**（适配主流版本，支持全量功能，无特殊权限限制）\r\n\r\n- **iOS**（适配主流版本，支持全量功能，遵循 iOS 文件操作规范）\r\n\r\n## 前置准备\r\n\r\n在集成插件前，需确保开发环境满足基础要求，完成必要的前置配置，具体步骤如下：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本；\r\n\r\n- 已全局安装 HCordova CLI（v10.0.0 及以上），用于插件的安装、卸载和管理；\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `cordova create zipDemo com.example.zip ZipDemo` 命令快速创建）；\r\n\r\n- OHOS 平台需确保应用已获取文件访问权限，避免因权限不足导致文件读取/写入失败；\r\n\r\n- 确保项目适配 OHOS 5.0 及以上版本，避免因系统版本过低导致插件功能异常；\r\n\r\n- 熟悉 OHOS 系统沙箱路径规范，了解 Cordova 插件在 OHOS 平台的文件访问方式。\r\n\r\n## 下载安装\r\n\r\n通过 HCordova CLI 即可快速安装插件，支持全平台安装或指定 OHOS 平台安装，安装流程简洁高效，安装后可通过命令验证安装结果。\r\n\r\n### 前提条件\r\n\r\n安装插件前，需先安装 HCordova CLI，执行以下命令安装：\r\n\r\n```bash\r\nnpm install -g hcordova\r\n```\r\n\r\n### 基础安装（推荐，从 npm 仓库）\r\n\r\n在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置，默认安装最新稳定版本：\r\n\r\n```bash\r\n# 安装最新稳定版（全平台）\r\nhcordova plugin add cordova-plugin-zip\r\n\r\n# 安装指定 OHOS 平台\r\nhcordova plugin add cordova-plugin-zip --platform ohos\r\n\r\n# 安装指定版本（仅 OHOS 平台）\r\nhcordova plugin add cordova-plugin-zip@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 安装开发版\r\n\r\n若需使用开发中的最新功能，可直接从 GitCode 仓库安装，仅适配 OHOS 平台：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-zip.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-zip.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-zip）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-zip  --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 卸载插件\r\n\r\n如需移除插件，执行以下命令即可清理相关配置与依赖，支持全平台卸载或指定 OHOS 平台卸载：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-zip\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-zip --platform ohos\r\n```\r\n\r\n## OHOS 配置\r\n\r\n### 1. 路径配置说明\r\n\r\nOHOS 平台需使用 Cordova 提供的沙箱路径常量，常用沙箱路径如下：\r\n\r\n- cordova.file.externalDataDirectory：应用外部数据目录，用于存储可持久化的文件，推荐用于压缩解压操作；\r\n\r\n- cordova.file.dataDirectory：应用内部数据目录，仅应用自身可访问，适合存储敏感文件；\r\n\r\n- 注意：所有压缩解压操作的文件路径，均需基于以上沙箱路径拼接，否则会导致文件无法访问。\r\n\r\n### 2. 加密配置说明\r\n\r\nOHOS 平台仅支持 ZIP 传统加密格式，若需解压加密 ZIP 文件，需确保加密方式为传统加密，高级加密（如 AES）会导致解压失败，且无法返回解密错误外的具体详细信息。\r\n\r\n## 约束与限制\r\n\r\n- 依赖插件：无强制依赖插件，@cordova-ohos/ohos 版本为 2.0.0 及以上；\r\n\r\n- 平台限制：OHOS 平台仅支持 5.0 及以上版本，低于该版本的系统可能出现文件访问异常、API 调用失败等问题；\r\n\r\n- 路径限制：仅支持 OHOS 系统沙箱路径，无法访问沙箱外的文件；\r\n\r\n- 加密限制：仅支持 ZIP 传统加密格式，不支持 AES 等高级加密格式，解密失败会返回 -1 错误码；\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `zip` 对象未定义、调用失败等异常；\r\n\r\n- 文件大小限制：支持大文件压缩解压，但建议单个 ZIP 文件大小不超过 1GB，避免占用过多系统资源导致操作超时；\r\n\r\n- 目录权限：解压目录需确保有写入权限，若目录不存在，插件会自动创建，但需确保父目录有写入权限。\r\n\r\n### 兼容性\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n插件通过全局对象 `zip` 暴露所有核心 API，支持回调函数方式调用，所有 API 需在 `deviceready` 事件触发后调用。以下为 OHOS 平台核心功能的完整使用示例，可直接复制到项目中使用，重点注意沙箱路径使用和权限配置。\r\n\r\n### 1. 基础解压 ZIP 文件（沙箱内文件）\r\n\r\n将沙箱内的 ZIP 文件解压到指定沙箱目录，包含进度监听，适配 OHOS 沙箱路径规范：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 进度监听函数：实时显示解压进度\r\n    function unzipProgressFun(progressEvent) {\r\n        var progress = (progressEvent.loaded / progressEvent.total * 100).toFixed(2);\r\n        document.getElementById(\"progress\").innerHTML = \"解压:\" + progress + \"%\";\r\n    }\r\n\r\n    /*\r\n    * path: 解压目标沙箱路径（需基于 Cordova 沙箱路径拼接）\r\n    * zipFile: 待解压 ZIP 文件的沙箱路径\r\n    */\r\n    // 示例：将沙箱内的 ceshi.zip 解压到 externalDataDirectory/zip 目录\r\n    var zipFile = cordova.file.externalDataDirectory + \"ceshi.zip\";\r\n    var targetPath = cordova.file.externalDataDirectory + \"zip/\";\r\n\r\n    zip.unzip(targetPath, zipFile, function(isOk){\r\n        if(isOk == -1) {\r\n            alert(\"解压失败，请检查文件路径、权限或加密格式\");\r\n        } else {\r\n            alert(\"解压成功，文件已保存至：\" + targetPath);\r\n        }\r\n    }, unzipProgressFun);\r\n}, false);\r\n```\r\n\r\n### 2. 下载并解压 ZIP 文件（完整场景）\r\n\r\n从网络下载 ZIP 文件到沙箱，再解压到指定目录，包含下载进度和解压进度监听，适用于实际业务场景：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 下载并解压完整函数\r\n    function downloadAndUnZip() {\r\n        // 解压进度监听\r\n        function unzipProgressFun(progressEvent) {\r\n            var progress = (progressEvent.loaded / progressEvent.total * 100).toFixed(2);\r\n            document.getElementById(\"progress\").innerHTML = \"解压:\" + progress + \"%\";\r\n        }\r\n\r\n        // 下载成功回调：开始解压\r\n        function successFun(fileEntry) {\r\n            console.log(\"下载完成，文件路径: \" + fileEntry.toURL());\r\n            // 获取沙箱目标解压目录\r\n            window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {\r\n                var targetPath = dirEntry.toURL() + \"zip/\";\r\n                // 执行解压操作\r\n                zip.unzip(targetPath, fileEntry.toURL(), function(isOk){\r\n                    if(isOk == -1) {\r\n                        alert(\"解压失败，请检查文件是否为合法 ZIP 格式或加密方式是否支持\");\r\n                    } else {\r\n                        alert(\"解压成功，文件已保存至：\" + targetPath);\r\n                    }\r\n                }, unzipProgressFun);\r\n            });\r\n        }\r\n\r\n        // 下载失败回调\r\n        function failFun(error) {\r\n            console.log(\"下载失败：Code = \" + error.code);\r\n            console.log(\"下载错误源：\" + error.source);\r\n            console.log(\"下载错误目标：\" + error.target);\r\n            alert('下载失败，请检查网络连接或文件地址');\r\n        }\r\n\r\n        // 下载进度监听\r\n        function progressFun(progressEvent) {\r\n            var progress = (progressEvent.loaded / progressEvent.total * 100).toFixed(2);\r\n            document.getElementById(\"progress\").innerHTML = \"下载：\" + progress + \"%\";\r\n        }\r\n\r\n        // 待下载 ZIP 文件地址\r\n        var uri = \"https://www.example.com/ceshi.zip\";\r\n        // 下载到沙箱的目标路径\r\n        window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {\r\n            var targetPath = dirEntry.toURL() + \"ceshi.zip\";\r\n            var fileTransfer = new FileTransfer();\r\n            // 绑定下载进度监听\r\n            fileTransfer.onprogress = progressFun;\r\n            // 执行下载\r\n            fileTransfer.download(\r\n                uri,\r\n                targetPath,\r\n                successFun,\r\n                failFun,\r\n                false,\r\n                {}\r\n            );\r\n        });\r\n    }\r\n\r\n    // 调用下载并解压函数\r\n    downloadAndUnZip();\r\n}, false);\r\n```\r\n\r\n## 使用说明\r\n\r\n以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性与限制。\r\n\r\n### 1. 核心 API 说明\r\n\r\n插件所有方法均挂载在全局 `zip` 对象下，无需额外引入，支持回调函数方式调用，所有 API 均需在 `deviceready` 事件触发后调用。\r\n\r\n#### 1.1 解压 ZIP 文件（核心 API）\r\n\r\n功能：将指定路径的 ZIP 文件解压到目标目录，支持进度监听和错误回调，适配 OHOS 沙箱路径。\r\n\r\n语法：\r\n\r\n```javascript\r\nzip.unzip(targetPath, zipFile, successCallback, progressCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- targetPath：解压目标目录路径，必填，需为 OHOS 沙箱路径（如 cordova.file.externalDataDirectory + \"zip/\"）；\r\n\r\n- zipFile：待解压 ZIP 文件的路径，必填，需为 OHOS 沙箱路径；\r\n\r\n- successCallback：成功回调，参数 isOk，1 表示解压成功，-1 表示解压失败；\r\n\r\n- progressCallback：进度回调，参数 progressEvent，包含 loaded（已处理字节数）和 total（总字节数），可计算进度百分比。\r\n\r\n### 2. 常见问题（FAQ）\r\n\r\n#### Q1: 调用解压 API 后返回 -1（解压失败）怎么办？\r\n\r\n1. 检查文件路径：确保 zipFile（待解压文件）和 targetPath（目标目录）均为 OHOS 沙箱路径，避免使用非沙箱路径；\r\n\r\n2. 检查 ZIP 文件：确认文件为合法 ZIP 格式，若为加密文件，需确保是传统加密格式（不支持 AES 加密）；\r\n\r\n3. 检查目录权限：确保目标解压目录有写入权限，若目录不存在，插件会自动创建，但需确保父目录有写入权限。\r\n\r\n#### Q2: 中文文件名解压后乱码怎么办？\r\n\r\n插件默认启用 UTF-8 编码，可解决中文文件名乱码问题。若仍出现乱码，需检查待压缩文件的编码格式，确保为 UTF-8，同时避免使用特殊字符（如特殊符号、全角空格）作为文件名。\r\n\r\n#### Q3: 进度监听无反应或进度不更新怎么办？\r\n\r\n1. 检查 API 调用顺序：确保进度回调函数在调用 unzip 方法前定义，避免回调函数未初始化；\r\n\r\n2. 检查文件大小：小文件（小于 1MB）压缩解压速度过快，可能导致进度回调只触发一次（100%），属于正常现象；\r\n\r\n3. 检查回调参数：确保进度回调函数正确接收 progressEvent 参数，且正确计算进度百分比。\r\n\r\n#### Q4: 解压大文件时出现超时或卡顿怎么办？\r\n\r\n建议单个 ZIP 文件大小不超过 1GB，同时在压缩解压过程中避免频繁操作应用，减少系统资源占用；可优化压缩级别（如降低至 4-6），平衡压缩速度和压缩率。\r\n\r\n#### Q5: 卸载插件后，沙箱内的压缩解压文件会被删除吗？\r\n\r\n不会。卸载插件仅清理插件相关的配置和依赖，沙箱内的文件（压缩包、解压后的文件）会保留，需手动删除或通过代码删除。\r\n\r\n### 3. 注意事项\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `zip` 对象未定义、调用失败等异常。\r\n\r\n- 权限配置：OHOS 平台必须添加文件访问权限，否则无法进行压缩解压操作，建议在应用启动时主动申请权限。\r\n\r\n- 路径规范：所有文件路径必须使用 OHOS 沙箱路径，推荐使用 Cordova 提供的路径常量（如 cordova.file.externalDataDirectory）。\r\n\r\n- 加密兼容：仅支持 ZIP 传统加密格式，不支持 AES 等高级加密，解压加密文件前需确认加密方式。\r\n\r\n- 错误处理：建议为所有 API 调用添加错误回调，便于捕获压缩解压失败的异常，根据错误信息快速定位问题。\r\n\r\n- 版本兼容性：确保 HCordova CLI、cordova-ohos、OHOS 系统版本符合要求，避免因版本不兼容导致插件功能异常。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-zip                   # [根目录] ZIP 压缩解压缩插件项目根目录\r\n├── src                              # [源码目录] 存放原生平台代码\r\n│   └── main                         # [主目录] 主代码目录\r\n│       └── cpp                      # [C++ 目录] C++ 原生代码目录\r\n│           └── minizip              # [C++ 模块] minizip 库文件夹（一个流行的 ZIP 处理库）\r\n│               ├── crypt.h          # [C 头文件] 加密相关头文件\r\n│               ├── ioapi.c          # [C 源文件] I/O API 实现\r\n│               ├── ioapi.h          # [C 头文件] I/O API 头文件\r\n│               ├── unzip.c          # [C 源文件] 解压缩功能实现\r\n│               ├── unzip.h          # [C 头文件] 解压缩功能头文件\r\n│               ├── Zip.cpp          # [C++ 源文件] ZIP 插件主逻辑实现\r\n│               ├── Zip.h            # [C++ 头文件] ZIP 插件接口定义\r\n│               ├── zip12.c          # [C 源文件] 压缩功能实现\r\n│               └── zip12.h          # [C 头文件] 压缩功能头文件\r\n├── www                              # [前端目录] 存放供 Web 端调用的 JS 接口文件\r\n│   └── zip.js                       # [JS 文件] 前端 JavaScript 接口，封装了原生 ZIP 功能\r\n├── .gitignore                       # [配置] Git 版本控制忽略文件配置\r\n├── LICENSE                          # [文本] 开源许可证文件\r\n├── OAT.xml                          # [配置] 门禁配置文件\r\n├── package.json                     # [配置] NPM 包配置文件，定义插件元数据和依赖\r\n├── plugin.xml                       # [配置] Cordova 插件配置文件，定义插件结构和平台特定设置\r\n└── README.md                        # [文档] 插件说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-zip/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-zip/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-zip 官方指南](https://www.npmjs.com/package/cordova-plugin-zip)\r\n\r\n- GitCode 仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-zip](https://gitcode.com/CPF-Cordova/cordova-plugin-zip)\r\n","readmeFilename":"README.md"}