鸿蒙三方库 | harmony-utils之FileUtil文件管理与目录详解

前言

文件管理包括文件创建、删除、复制、移动以及目录操作等。@pura/harmony-utils 的 FileUtil 封装了文件管理和目录操作方法，简化了文件系统操作。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil管理核心API

FileUtil 提供了以下文件管理方法：

方法	说明	返回类型	使用场景
`exists(path)`	文件是否存在	boolean	存在检查
`isFile(path)`	是否文件	boolean	类型判断
`isDirectory(path)`	是否目录	boolean	类型判断
`createFile(path)`	创建文件	void	文件创建
`createDirectory(path)`	创建目录	void	目录创建
`delete(path)`	删除文件或目录	void	文件清理
`rename(path, newName)`	重命名	void	文件重命名
`copy(src, dest)`	复制文件	void	文件备份
`move(src, dest)`	移动文件	void	文件整理
`getFilesDir()`	获取应用文件目录	string	路径获取
`getCacheDir()`	获取缓存目录	string	缓存路径
`listFiles(path)`	列出目录文件	string\[\]	文件浏览

1.1 核心特性

简洁易用：封装复杂逻辑为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
全面覆盖：覆盖文件和目录的增删改查操作

1.2 目录类型对照

目录	方法	说明	生命周期
文件目录	getFilesDir	应用私有文件	随应用
缓存目录	getCacheDir	临时缓存	系统可清理
临时目录	getTempDir	临时文件	随时清理

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 文件存在判断

typescript 复制代码

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

Button('文件存在判断')
  .width('100%')
  .onClick(() => {
    try {
      let path = FileUtil.getFilesDir() + '/test.txt';
      let exists = FileUtil.exists(path);
      this.result = `${path}\n存在: ${exists ? '是 ✅' : '否 ❌'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 创建与删除

typescript 复制代码

Button('创建与删除')
  .width('100%')
  .onClick(() => {
    try {
      let dir = FileUtil.getFilesDir() + '/mydir';
      FileUtil.createDirectory(dir);
      FileUtil.createFile(dir + '/note.txt');
      this.result = `目录和文件已创建 ✅`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

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

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

  build() {
    Column({ space: 12 }) {
      Button('文件目录').width('100%').onClick(() => {
        this.result = `文件: ${FileUtil.getFilesDir()}\n缓存: ${FileUtil.getCacheDir()}`;
      });
      Button('创建目录').width('100%').onClick(() => {
        FileUtil.createDirectory(FileUtil.getFilesDir() + '/demo');
        this.result = '目录已创建';
      });
      Button('列出文件').width('100%').onClick(() => {
        let files = FileUtil.listFiles(FileUtil.getFilesDir());
        this.result = `文件数: ${files.length}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 缓存管理

typescript 复制代码

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

function clearCache(): void {
  let cacheDir = FileUtil.getCacheDir();
  let files = FileUtil.listFiles(cacheDir);
  files.forEach(file => {
    FileUtil.delete(file);
  });
}

4.2 文件备份

typescript 复制代码

function backupFile(srcPath: string): string {
  let backupDir = FileUtil.getFilesDir() + '/backup';
  FileUtil.createDirectory(backupDir);
  let fileName = srcPath.split('/').pop();
  let destPath = backupDir + '/' + fileName;
  FileUtil.copy(srcPath, destPath);
  return destPath;
}

五、注意事项

路径安全：使用FileUtil提供的方法获取安全路径
删除不可逆：delete操作不可恢复，谨慎使用
目录递归：delete删除目录时可能递归删除所有内容
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
并发安全：多线程同时操作同一文件需注意并发安全

六、常见问题

Q1: delete删除目录会删除子文件吗？

通常会的，delete删除目录时会递归删除所有子文件和子目录。

Q2: copy可以复制目录吗？

取决于实现，部分只支持文件复制，目录需递归处理。

Q3: getFilesDir返回的路径应用卸载后还在吗？

不在了，应用私有目录随应用卸载而被清除。

Q4: 如何获取外部存储路径？

HarmonyOS使用沙箱机制，应用只能访问自己的目录。

总结

FileUtil 的文件管理和目录方法为文件系统操作提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现文件管理、缓存清理等功能。

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