HarmonyOS ohos.zlib (Zip模块) 使用指南从入门到实战模块类型系统内置模块关键词文件压缩、文件解压、Zip、zlib、ArkTS效果一、模块概述ohos.zlib是 HarmonyOS 提供的文件压缩与解压模块基于 zlib 算法库实现支持对文件进行压缩compressFile和解压decompressFile操作。该模块同时提供同步和异步两种调用方式适用于文件归档、批量传输、缓存管理等场景。核心能力一览能力方法说明压缩文件compressFile将文件或目录压缩为.zip文件解压文件decompressFile将.zip文件解压到目标目录压缩等级CompressLevel支持 0~9 级压缩以及默认、最佳速度、最佳压缩比内存等级MemLevel控制压缩时的内存分配策略压缩策略CompressStrategy默认策略、过滤策略、霍夫曼编码策略二、API 详解2.1 导入模块importzlibfromohos.zlib;import{BusinessError}fromohos.base;2.2 Options 配置项compressFile和decompressFile共享同一个Options接口interfaceOptions{level?:CompressLevel;// 压缩等级默认 COMPRESS_LEVEL_DEFAULT_COMPRESSIONmemLevel?:MemLevel;// 内存等级默认 MEM_LEVEL_DEFAULTstrategy?:CompressStrategy;// 压缩策略默认 COMPRESS_STRATEGY_DEFAULT_STRATEGY}CompressLevel 枚举值枚举值说明COMPRESS_LEVEL_NO_COMPRESSION不压缩 (0)COMPRESS_LEVEL_BEST_SPEED最佳速度 (1)COMPRESS_LEVEL_BEST_COMPRESSION最佳压缩比 (9)COMPRESS_LEVEL_DEFAULT_COMPRESSION默认等级 (6)经验提示日常场景使用DEFAULT_COMPRESSION即可在速度与压缩率之间取得平衡。对于大文件且对速度敏感的场景可选BEST_SPEED。2.3 compressFile —— 压缩文件// 异步回调方式zlib.compressFile(inFile:string,// 待压缩的文件或目录路径outFile:string,// 输出的 .zip 文件路径options:Options,// 压缩选项callback:AsyncCallbackvoid):void;// Promise 方式zlib.compressFile(inFile:string,outFile:string,options:Options):Promisevoid;2.4 decompressFile —— 解压文件// 异步回调方式zlib.decompressFile(inFile:string,// .zip 压缩文件路径outFile:string,// 解压目标目录路径options:Options,// 解压选项callback:AsyncCallbackvoid):void;// Promise 方式zlib.decompressFile(inFile:string,outFile:string,options:Options):Promisevoid;三、实战示例压缩与解压完整流程3.1 场景说明实现一个完整的文件操作链路创建临时目录和测试文件将目录压缩为.zip文件将.zip文件解压到另一个目录验证解压结果3.2 完整代码importzlibfromohos.zlib;importfsfromohos.file.fs;import{BusinessError}fromohos.base;import{Context}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;constTAGZlibDemo;/** * 步骤一创建测试文件 */functioncreateTestFile(filePath:string):void{letfile:fs.File|nullnull;try{filefs.openSync(filePath,fs.OpenMode.READ_WRITE|fs.OpenMode.CREATE);constcontentHello HarmonyOS! This is a zlib compression test file.;fs.writeSync(file.fd,content);hilog.info(0x0001,TAG,文件创建成功:${filePath});}catch(err){hilog.error(0x0001,TAG,创建文件失败:${(errasBusinessError).message});}finally{if(file!null){fs.closeSync(file);}}}/** * 步骤二压缩文件回调方式 */functioncompressDemo(context:Context):void{constsourceDir${context.cacheDir}/demo_source;constzipPath${context.cacheDir}/demo.zip;// 确保源目录存在try{fs.mkdirSync(sourceDir);}catch(_e){// 目录已存在}// 创建测试文件createTestFile(${sourceDir}/readme.txt);createTestFile(${sourceDir}/data.txt);// 执行压缩constoptions:zlib.Options{level:zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION,memLevel:zlib.MemLevel.MEM_LEVEL_DEFAULT,strategy:zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY};zlib.compressFile(sourceDir,zipPath,options,(err:BusinessError){if(err!nullerr.code!0){hilog.error(0x0001,TAG,压缩失败: code${err.code}, msg${err.message});return;}hilog.info(0x0001,TAG,压缩成功输出:${zipPath});});}/** * 步骤三解压文件Promise 方式 */asyncfunctiondecompressDemo(context:Context):Promisevoid{constzipPath${context.cacheDir}/demo.zip;constextractDir${context.cacheDir}/demo_extracted;constoptions:zlib.Options{level:zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION};try{awaitzlib.decompressFile(zipPath,extractDir,options);hilog.info(0x0001,TAG,解压成功输出目录:${extractDir});}catch(err){constbizErrerrasBusinessError;hilog.error(0x0001,TAG,解压失败: code${bizErr.code}, msg${bizErr.message});}}3.3 调用入口// 在页面的 aboutToAppear 或按钮点击中调用compressDemo(context);decompressDemo(context);四、两种调用方式对比特性回调方式 (callback)Promise 方式语法风格传统回调async/await错误处理回调参数判断try/catch链式操作嵌套回调顺序编写推荐使用需要与 Worker 配合时主线程简单调用推荐优先使用 Promise 方式配合async/await可使代码更清晰可读。五、注意事项5.1 路径规范inFile和outFile必须是应用沙箱路径如context.cacheDir、context.filesDir。解压目标目录不需要预先创建decompressFile会自动创建。5.2 权限说明ohos.zlib操作的是应用沙箱内的文件无需额外申请权限。5.3 大文件处理对于较大文件50MB建议将压缩/解压操作放在Worker 线程中执行避免阻塞主线程。使用COMPRESS_LEVEL_BEST_SPEED提升压缩速度。关注内存占用适当降低memLevel。5.4 错误码错误码含义处理建议901001输入文件不存在检查源文件路径901002输出路径无效检查目标目录权限901003不支持的压缩格式确认为标准 zip 格式六、最佳实践总结✅ 使用沙箱路径确保数据安全 ✅ 大文件放 Worker 线程保持 UI 流畅 ✅ 始终处理错误回调避免静默失败 ✅ 操作完成后及时关闭文件描述符 ✅ 根据场景选择合适的压缩等级