前言

文件列表和递归遍历是文件管理的高级功能，用于查看目录内容和搜索文件。@pura/harmony-utils 的 FileUtil 封装了文件列表和遍历方法，支持递归遍历子目录。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil遍历核心API

FileUtil 提供了以下文件列表和遍历方法：

方法	说明	返回类型	使用场景
listFile(path)	列出目录文件	string[]	目录内容查看
listDir(path)	列出目录内容	string[]	目录浏览
walkFile(path, callback)	递归遍历	void	文件搜索

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 递归支持：支持递归遍历子目录

1.2 遍历方法对照

方法	遍历深度	返回内容	适用场景
listFile	仅当前目录	文件名列表	简单浏览
listDir	仅当前目录	文件和目录列表	目录浏览
walkFile	递归子目录	逐个回调	深度搜索

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 列出目录文件

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

Button('列出目录文件')
  .width('100%')
  .onClick(() => {
    try {
      let files = FileUtil.listFile(FileUtil.getFilesDir());
      this.result = `文件数量: ${files.length}\n${files.slice(0, 5).join('\n')}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 递归遍历

Button('递归遍历')
  .width('100%')
  .onClick(() => {
    try {
      let count = 0;
      FileUtil.walkFile(FileUtil.getFilesDir(), (path: string) => {
        count++;
      });
      this.result = `遍历完成 ✅\n共发现 ${count} 个文件`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('列出文件').width('100%').onClick(() => {
        try {
          let files = FileUtil.listFile(FileUtil.getFilesDir());
          this.result = `共 ${files.length} 个文件\n${files.join('\n')}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 文件搜索

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

function searchFiles(dir: string, keyword: string): string[] {
  let results: string[] = [];
  FileUtil.walkFile(dir, (path: string) => {
    if (path.includes(keyword)) {
      results.push(path);
    }
  });
  return results;
}

4.2 按扩展名过滤

function filterByExtension(dir: string, ext: string): string[] {
  let results: string[] = [];
  FileUtil.walkFile(dir, (path: string) => {
    if (path.endsWith('.' + ext)) {
      results.push(path);
    }
  });
  return results;
}

五、注意事项

1. 性能影响：递归遍历大量文件可能耗时
2. 权限要求：遍历需要目录的读取权限
3. 路径格式：返回的路径为绝对路径
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 目录深度：过深的目录结构可能导致栈溢出

六、常见问题

Q1: listFile()返回空数组？

可能是目录为空，或没有读取权限，检查目录路径和权限。

Q2: walkFile()遍历很慢？

文件数量过多时遍历较慢，建议限制遍历深度或使用异步方式。

Q3: 如何只遍历文件不遍历目录？

在回调中使用 FileUtil.isFile() 判断是否为文件。

Q4: 遍历过程中可以删除文件吗？

不建议在遍历过程中删除文件，可能导致遍历结果不完整。

总结

FileUtil 的文件列表和遍历方法为文件管理提供了强大的搜索能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据需求选择合适的遍历方式。

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