蒙三方库 | harmony-utils之FileUtil文件重命名与属性查询详解

前言

文件重命名和属性查询是文件管理的重要操作。@pura/harmony-utils 的 FileUtil 封装了文件重命名和属性查询方法，开发者可以轻松获取文件大小、修改时间等属性。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil属性核心API

FileUtil 提供了以下文件属性查询方法：

方法	说明	返回类型	使用场景
`rename(oldPath, newPath)`	重命名文件	void	文件整理
`getFileInfo(path)`	获取文件属性	FileInfo	属性查看
`getFileSize(path)`	获取文件大小	number	大小展示
`isDirectory(path)`	是否目录	boolean	类型判断
`isFile(path)`	是否文件	boolean	类型判断

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
属性全面：覆盖文件大小、类型等常用属性

1.2 文件属性信息对照

属性	获取方法	说明	示例值
文件大小	getFileSize	字节数	1024
是否文件	isFile	布尔值	true
是否目录	isDirectory	布尔值	false
文件信息	getFileInfo	FileInfo对象	-

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 文件重命名

typescript 复制代码

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

Button('重命名文件')
  .width('100%')
  .onClick(() => {
    try {
      let oldPath = FileUtil.getFilesDir() + '/old.txt';
      let newPath = FileUtil.getFilesDir() + '/new.txt';
      FileUtil.rename(oldPath, newPath);
      this.result = '重命名成功 ✅\nold.txt → new.txt';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 查询文件属性

typescript 复制代码

Button('查询文件属性')
  .width('100%')
  .onClick(() => {
    try {
      let path = FileUtil.getFilesDir() + '/test.txt';
      let isFile = FileUtil.isFile(path);
      let size = FileUtil.getFileSize(path);
      this.result = `是文件: ${isFile}\n大小: ${size}字节`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

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

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

  build() {
    Column({ space: 12 }) {
      Button('查询属性').width('100%').onClick(() => {
        try {
          let path = FileUtil.getFilesDir() + '/test.txt';
          let exists = FileUtil.exists(path);
          let isFile = FileUtil.isFile(path);
          this.result = `存在: ${exists}\n是文件: ${isFile}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 文件信息展示

typescript 复制代码

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

function getFileDetail(path: string): Record<string, Object> {
  return {
    path: path,
    exists: FileUtil.exists(path),
    isFile: FileUtil.isFile(path),
    isDir: FileUtil.isDirectory(path),
    size: FileUtil.formatFileSize(FileUtil.getFileSize(path))
  };
}

4.2 批量重命名

typescript 复制代码

function batchRename(dir: string, prefix: string): void {
  let files = FileUtil.listFile(dir);
  files.forEach((file, index) => {
    let ext = file.split('.').pop() || '';
    FileUtil.rename(dir + '/' + file, dir + '/' + prefix + '_' + index + '.' + ext);
  });
}

五、注意事项

重命名路径：新旧路径必须在同一文件系统
文件存在：查询属性前建议先检查文件是否存在
大小精度：文件大小以字节为单位
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
并发安全：重命名操作期间不要同时读写该文件

六、常见问题

Q1: 重命名时提示跨文件系统？

源路径和目标路径必须在同一分区，不能跨分区重命名。

Q2: getFileSize()返回0？

Q3: isFile()和isDirectory()都返回false？

可能是文件不存在，先用 exists() 检查。

Q4: 重命名后原路径文件还在吗？

重命名成功后原路径文件不存在，已移动到新路径。

总结

FileUtil 的文件属性查询和重命名方法为文件管理提供了重要支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现文件信息展示和批量操作。

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