鸿蒙三方库 | harmony-utils之FileUtil文件读写操作详解

SansanDoris

99人浏览 · 2026-07-19 00:34:09

SansanDoris · 2026-07-19 00:34:09 发布

前言

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

一、FileUtil读写核心API

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

方法	说明	返回类型	使用场景
`readTextSync(path)`	同步读取文本	string	配置文件读取
`writeTextSync(path, text)`	同步写入文本	void	日志文件写入
`readArrayBufferSync(path)`	同步读取二进制	ArrayBuffer	图片/音频读取
`writeArrayBufferSync(path, buffer)`	同步写入二进制	void	二进制数据保存

1.1 核心特性

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

1.2 读写模式对照

模式	方法	适用数据	性能
文本模式	readTextSync/writeTextSync	字符串	适合小文件
二进制模式	readArrayBufferSync/writeArrayBufferSync	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.writeTextSync(path, 'Hello harmony-utils!');
      this.result = `写入成功 ✅\n路径: ${path}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

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

2.3 二进制文件读写

Button('写入二进制')
  .width('100%')
  .onClick(() => {
    try {
      let path = FileUtil.getFilesDir() + '/data.bin';
      let buffer = new ArrayBuffer(4);
      FileUtil.writeArrayBufferSync(path, buffer);
      this.result = '二进制写入成功';
    } 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(() => {
        try {
          let path = FileUtil.getFilesDir() + '/demo.txt';
          FileUtil.writeTextSync(path, 'Hello World!');
          this.result = '写入成功';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('读取文件').width('100%').onClick(() => {
        try {
          let path = FileUtil.getFilesDir() + '/demo.txt';
          let content = 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';

function saveConfig(config: Record<string, Object>): void {
  let path = FileUtil.getFilesDir() + '/config.json';
  FileUtil.writeTextSync(path, JSON.stringify(config));
}

function loadConfig(): Record<string, Object> {
  let path = FileUtil.getFilesDir() + '/config.json';
  let content = FileUtil.readTextSync(path);
  return JSON.parse(content) as Record<string, Object>;
}

4.2 日志文件追加

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