前言

文件读写是应用数据持久化的基础操作，如配置文件、日志文件、缓存数据等。@pura/harmony-utils 的 FileUtil 封装了文件读写方法，简化了文件操作。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil读写核心API

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

方法	说明	返回类型	使用场景
readText(path)	读取文本文件	string	配置读取
writeText(path, content)	写入文本文件	void	数据保存
appendText(path, content)	追加文本	void	日志追加
readArrayBuffer(path)	读取二进制文件	ArrayBuffer	二进制读取
writeArrayBuffer(path, buffer)	写入二进制文件	void	二进制保存

1.1 核心特性

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

1.2 读写方法对照

方法	操作	数据类型	适用场景
readText	读	string	文本文件
writeText	写	string	文本保存
appendText	追加	string	日志追加
readArrayBuffer	读	ArrayBuffer	图片/音频
writeArrayBuffer	写	ArrayBuffer	二进制保存

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 写入文本文件

import { FileUtil } from '@pura/harmony-utils';

Button('写入文本文件')
  .width('100%')
  .onClick(() => {
    try {
      let path = FileUtil.getFilesDir() + '/test.txt';
      FileUtil.writeText(path, 'Hello harmony-utils!');
      this.result = `写入成功 ✅\n路径: ${path}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 读取文本文件

Button('读取文本文件')
  .width('100%')
  .onClick(() => {
    try {
      let path = FileUtil.getFilesDir() + '/test.txt';
      let content = FileUtil.readText(path);
      this.result = `读取成功 ✅\n内容: ${content}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { FileUtil } from '@pura/harmony-utils';

@Entry
@Component
struct FileRWDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('写入文件').width('100%').onClick(() => {
        let path = FileUtil.getFilesDir() + '/demo.txt';
        FileUtil.writeText(path, 'Hello harmony-utils!');
        this.result = '写入成功';
      });
      Button('读取文件').width('100%').onClick(() => {
        let path = FileUtil.getFilesDir() + '/demo.txt';
        this.result = FileUtil.readText(path);
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 日志文件追加

import { FileUtil, DateUtil } from '@pura/harmony-utils';

function appendLog(message: string): void {
  let path = FileUtil.getFilesDir() + '/app.log';
  let timestamp = DateUtil.formatNow('yyyy-MM-dd HH:mm:ss');
  FileUtil.appendText(path, `[${timestamp}] ${message}\n`);
}

4.2 JSON配置文件

async function saveConfig(config: AppConfig): Promise<void> {
  let path = FileUtil.getFilesDir() + '/config.json';
  let json = JSON.stringify(config);
  FileUtil.writeText(path, json);
}

function loadConfig(): AppConfig | null {
  let path = FileUtil.getFilesDir() + '/config.json';
  let json = FileUtil.readText(path);
  return json ? JSON.parse(json) : null;
}

五、注意事项

1. 路径安全：使用FileUtil.getFilesDir()获取安全路径
2. 文件权限：应用只能访问自己的文件目录
3. 写入覆盖：writeText会覆盖已有文件内容
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 大文件处理：大文件建议使用流式读取

六、常见问题

Q1: 文件保存在哪里？

使用getFilesDir()获取应用私有目录，应用卸载后文件会被删除。

Q2: writeText会覆盖原有内容吗？

是的，writeText会覆盖。如需追加请使用appendText。

Q3: 读取不存在的文件会怎样？

会抛出异常，建议先使用exists()检查文件是否存在。

Q4: 可以访问其他应用的文件吗？

不可以，应用沙箱机制限制了文件访问范围。

总结

FileUtil 的文件读写方法为数据持久化提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现配置文件、日志文件等功能。

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