前言

文件读写是最基础的文件操作，@pura/harmony-utils的FileUtil封装了简洁的文件读写方法，支持文本和二进制数据的读写，开发者无需手动管理文件流。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil读写核心API

FileUtil提供了以下文件读写方法：

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 双模式支持：同时支持文本和二进制读写

1.2 读写模式对照

二、完整使用步骤

2.1 安装依赖

ohpminstall@pura/harmony-utils

2.2 文本文件读写

import{FileUtil}from'@pura/harmony-utils';Button('写入文本文件').width('100%').onClick(()=>{try{letpath=FileUtil.getFilesDir()+'/test.txt';FileUtil.writeTextSync(path,'Hello harmony-utils!');this.result=`写入成功 ✅\n路径:${path}`;}catch(e){this.result='异常: '+e;}})Button('读取文本文件').width('100%').onClick(()=>{try{letpath=FileUtil.getFilesDir()+'/test.txt';letcontent=FileUtil.readTextSync(path);this.result=`读取成功 ✅\n内容:${content}`;}catch(e){this.result='异常: '+e;}})

2.3 二进制文件读写

Button('写入二进制').width('100%').onClick(()=>{try{letpath=FileUtil.getFilesDir()+'/data.bin';letbuffer=newArrayBuffer(4);FileUtil.writeArrayBufferSync(path,buffer);this.result='二进制写入成功';}catch(e){this.result='异常: '+e;}})

三、完整页面示例

import{FileUtil}from'@pura/harmony-utils';@Entry@Componentstruct FileRWDemo{@Stateresult:string='';build(){Column({space:12}){Button('写入文件').width('100%').onClick(()=>{try{letpath=FileUtil.getFilesDir()+'/demo.txt';FileUtil.writeTextSync(path,'Hello World!');this.result='写入成功';}catch(e){this.result='异常: '+e;}});Button('读取文件').width('100%').onClick(()=>{try{letpath=FileUtil.getFilesDir()+'/demo.txt';letcontent=FileUtil.readTextSync(path);this.result=`内容:${content}`;}catch(e){this.result='异常: '+e;}});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}

四、进阶用法

4.1 JSON配置文件读写

import{FileUtil}from'@pura/harmony-utils';functionsaveConfig(config:Record<string,Object>):void{letpath=FileUtil.getFilesDir()+'/config.json';FileUtil.writeTextSync(path,JSON.stringify(config));}functionloadConfig():Record<string,Object>{letpath=FileUtil.getFilesDir()+'/config.json';letcontent=FileUtil.readTextSync(path);returnJSON.parse(content)asRecord<string,Object>;}

4.2 日志文件追加

functionappendLog(message:string):void{letpath=FileUtil.getFilesDir()+'/app.log';letexisting='';try{existing=FileUtil.readTextSync(path);}catch(e){}FileUtil.writeTextSync(path,existing+message+'\n');}

五、注意事项

1. 同步方法：读写方法为同步调用，大文件建议使用流式操作
2. 文件路径：路径必须为应用沙箱内的有效路径
3. 编码格式：文本读写默认使用UTF-8编码
4. 初始化依赖：使用前需确保AppUtil.init()已调用
5. 文件大小：大文件读写可能导致内存溢出

六、常见问题

Q1: 读取文件时提示文件不存在？

先检查文件路径是否正确，再使用FileUtil.exists()确认文件是否存在。

Q2: 写入文件后读不到内容？

确认写入路径和读取路径一致，检查是否写入成功。

Q3: 如何追加内容而不是覆盖？

先读取原内容，拼接新内容后再写入。

Q4: 二进制文件和文本文件有什么区别？

文本文件以字符串形式读写，二进制文件以ArrayBuffer形式读写。图片、音频等应使用二进制模式。

总结

FileUtil的文件读写方法为应用数据持久化提供了基础支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据数据类型选择合适的读写模式。

本文基于@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。