前言

文件大小通常以字节为单位，但用户更习惯看到KB、MB、GB等易读格式。@pura/harmony-utils 的 FileUtil 封装了文件大小格式化方法，自动选择合适的单位进行展示。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil大小格式化核心API

FileUtil 提供了以下文件大小格式化方法：

方法	说明	返回类型	使用场景
formatFileSize(bytes)	格式化文件大小	string	UI展示
getFileSize(path)	获取文件大小（字节）	number	大小计算

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 自动换算：自动选择最合适的单位展示

1.2 格式化单位对照

字节范围	显示单位	示例
< 1024	B	512B
1024 - 1048575	KB	1.5KB
1048576 - 1073741823	MB	2.3MB
>= 1073741824	GB	1.2GB

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 格式化文件大小

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

Button('格式化文件大小')
  .width('100%')
  .onClick(() => {
    try {
      let size1 = FileUtil.formatFileSize(512);
      let size2 = FileUtil.formatFileSize(1024);
      let size3 = FileUtil.formatFileSize(1048576);
      let size4 = FileUtil.formatFileSize(1073741824);
      this.result = `512B = ${size1}\n1024B = ${size2}\n1MB = ${size3}\n1GB = ${size4}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 获取并格式化文件大小

Button('获取文件大小')
  .width('100%')
  .onClick(() => {
    try {
      let path = FileUtil.getFilesDir() + '/test.txt';
      let bytes = FileUtil.getFileSize(path);
      let formatted = FileUtil.formatFileSize(bytes);
      this.result = `原始: ${bytes}B\n格式化: ${formatted}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('格式化大小').width('100%').onClick(() => {
        let sizes = [512, 1024, 1536, 1048576, 1073741824];
        let results = sizes.map(s => `${s}B = ${FileUtil.formatFileSize(s)}`);
        this.result = results.join('\n');
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 存储空间统计

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

function calculateDirSize(dirPath: string): string {
  let totalSize = 0;
  FileUtil.walkFile(dirPath, (path: string) => {
    if (FileUtil.isFile(path)) {
      totalSize += FileUtil.getFileSize(path);
    }
  });
  return FileUtil.formatFileSize(totalSize);
}

4.2 文件大小比较

function compareFileSize(path1: string, path2: string): number {
  let size1 = FileUtil.getFileSize(path1);
  let size2 = FileUtil.getFileSize(path2);
  return size1 - size2;
}

五、注意事项

1. 精度：格式化结果保留1-2位小数
2. 单位选择：自动选择最合适的单位
3. 负数处理：不支持负数，传入负数可能异常
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 大文件：超过2GB的文件注意数值溢出

六、常见问题

Q1: formatFileSize()可以指定单位吗？

当前版本自动选择单位，如需指定单位可自行计算转换。

Q2: 格式化后的小数位数可以控制吗？

默认保留1-2位有效小数，具体精度取决于实现。

Q3: getFileSize()对目录返回什么？

目录的大小通常返回0或目录元数据大小，不包含子文件大小。

Q4: 如何计算目录总大小？

需要递归遍历目录下所有文件，累加每个文件的大小。

总结

FileUtil 的文件大小格式化方法为用户友好的文件大小展示提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法优化文件管理界面的展示效果。

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