鸿蒙编译框架@ohos/hvigor FileUtil用法

@ohos/hvigor FileUtil用法

在鸿蒙（HarmonyOS）开发中，@ohos/hvigor 的 FileUtil 是用于文件操作的实用工具类，提供了跨平台的文件读写、路径处理等常用方法。以下是其核心用法和示例：

一、核心方法说明

|-----|------|---|-----------------------------------|----------------------------------------------------------------------------|---|
| 方法名 | 功能描述 | | --------------------------------- | -------------------------------------------------------------------------- | |

| readFile(path: string) | 异步读取文件内容（返回 Promise<string>） |

| writeFile(path: string, content: string) | 异步写入文件内容（自动创建目录） |

| copyFile(src: string, dest: string) | 异步复制文件（支持覆盖） |

| deleteFile(path: string) | 异步删除文件 | |

| mkdirs(dirPath: string) | 递归创建目录 |

| exists(path: string) | 检查文件或目录是否存在（返回 Promise<boolean>） |

| listFiles(dirPath: string) | 列出目录下所有文件（返回 Promise<string[]>） |

| normalizePath(path: string) | 标准化路径（跨平台处理路径分隔符） |

二、基础用法示例

1. 读取文件内容

复制代码

import { FileUtil } from '@ohos/hvigor';

async function readConfig() {
  const content = await FileUtil.readFile('src/main/resources/config.json');
  console.log('配置文件内容:', content);
}

2. 写入文件

复制代码

async function generateVersionFile() {
  const version = '1.0.0';
  await FileUtil.writeFile('build/version.txt', `Version: ${version}`);
}

3. 复制资源文件

复制代码

async function copyAssets() {
  await FileUtil.copyFile('assets/raw/icon.png', 'build/res/icon.png');
}

4. 递归创建目录

复制代码

async function prepareDirs() {
  await FileUtil.mkdirs('build/generated/code');
}

三、实战场景

场景 1：动态生成配置文件

复制代码

import { FileUtil } from '@ohos/hvigor';

class ConfigGeneratorPlugin implements HvigorPlugin {
  apply(context: HvigorContext) {
    context.taskRegistry.registerTask('generateConfig', async () => {
      const config = {
        apiUrl: 'https://api.example.com',
        debug: context.getBuildType() === 'debug'
      };
      await FileUtil.writeFile(
        'build/generated/config.json', 
        JSON.stringify(config, null, 2)
      );
    });
  }
}

场景 2：清理构建产物

复制代码

async function cleanBuild() {
  const files = await FileUtil.listFiles('build');
  for (const file of files) {
    await FileUtil.deleteFile(file);
  }
}

四、路径处理技巧

结合 FileUtil.normalizePath 处理跨平台路径：

复制代码

const winPath = 'src\\main\\resources';
const unixPath = FileUtil.normalizePath(winPath); // 转换为 'src/main/resources'

五、错误处理

复制代码

async function safeRead(path: string) {
  try {
    if (await FileUtil.exists(path)) {
      return await FileUtil.readFile(path);
    }
    return '';
  } catch (err) {
    console.error('文件操作失败:', err.message);
    throw err;
  }
}

六、与 Node.js fs 模块对比

| 特性 | FileUtil | Node.js fs | |---------------------|-------------------------------------|--------------------------------|

| API 风格 | Promise-based | Callback/Promise/Sync 混合 |

| 目录自动创建 | 写文件时自动创建父目录 | 需要手动处理 |

| 跨平台路径 | 内置 normalizePath | 需依赖 path 模块 |

| 鸿蒙集成 | 深度集成 Hvigor 构建流程 | 通用文件操作 |

七、注意事项

路径基准 ：相对路径基于 模块根目录 （含 hvigorfile.ts 的目录）
性能优化 ：批量操作建议使用 listFiles + 循环处理
权限问题：确保对目标目录有写权限

通过 FileUtil 可以更便捷地实现构建流程中的文件操作，建议结合 Hvigor 官方文档深入使用。