欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在应用开发中，我们经常需要显示文件大小：

• 下载进度条： 15.4 MB / 102.0 MB
• 缓存管理页面： Clean 234.5 KB
• 系统存储详情： Available: 12.1 GB

如果直接显示字节数 12345678 Bytes，用户会一脸茫然。我们需要将字节转换成 KB, MB, GB 等单位，并保留适当的小数位。

虽然写一个除法函数很简单，但要处理好边缘情况（如 1024 vs 1000 进制，小数点保留，单位后缀 KiB vs KB），还是直接用现成的库来得稳妥。

filesize 就是这样一个极简的 Dart 库，专门把数字变成人类能看懂的字符串。

一、核心功能

它的功能只有一个：Int -> String。

支持：

1. 自动单位选择：自动判断数值大小，选用 B, KB, MB, GB, TB, PB, EB, ZB, YB。
2. 小数位控制：默认 2 位，可自定义。
3. 标准选择：虽然默认通常是 1 KB = 1024 Bytes，但也有些标准（如磁盘厂商）使用 1000。

二、集成与用法详解

2.1 添加依赖

dependencies:
  filesize: ^2.0.1

2.2 基础用法

import 'package:filesize/filesize.dart';

void main() {
  print(filesize(1024)); // "1 KB"
  print(filesize(1024 * 1024)); // "1 MB"
  print(filesize(123456)); // "120.56 KB"
  
  // 指定小数位
  print(filesize(123456, 0)); // "121 KB" (四舍五入)
}

三、OpenHarmony 适配实战：文件管理器

在鸿蒙上开发文件管理器或下载器时，这个库非常实用。

3.1 下载进度展示

假设我们使用 dio 下载文件。

import 'package:dio/dio.dart';
import 'package:filesize/filesize.dart';

void downloadFile(String url, String savePath) async {
  final dio = Dio();
  await dio.download(
    url, 
    savePath,
    onReceiveProgress: (received, total) {
      if (total != -1) {
        // 实时显示进度： "12.5 MB / 50.0 MB"
        final receivedStr = filesize(received);
        final totalStr = filesize(total);
        print('Progress: $receivedStr / $totalStr');
      }
    },
  );
}

3.2 缓存清理

结合 path_provider (适配鸿蒙后) 和 dart:io 计算缓存目录大小。

import 'dart:io';
import 'package:filesize/filesize.dart';

Future<String> getCacheSize(Directory cacheDir) async {
  int totalBytes = 0;
  try {
    if (await cacheDir.exists()) {
      await for (var file in cacheDir.list(recursive: true, followLinks: false)) {
        if (file is File) {
          totalBytes += await file.length();
        }
      }
    }
  } catch (e) {
    print(e);
  }
  
  // 转换为易读格式
  return filesize(totalBytes);
}

四、为什么不用手写？

你可以手写，但你会遇到：

1. 代码重复：每个项目都要拷一遍 formatBytes 函数。
2. 单位标准：KiB (IEC标准，1024) 和 KB (SI标准，1000) 的区别。filesize 库虽然简单，但至少帮你统一了标准（目前该库主要按 1024 计算，显示常规后缀）。
3. 极小体积：这个库非常小，几乎不增加包体积。

五、总结

filesize 是那种“麻雀虽小，五脏俱全”的库。

对于 OpenHarmony 开发者：

• 统一体验：确保你的 App 中所有关于容量的显示格式一致。
• 纯 Dart：无平台依赖，完全兼容。

在任何涉及 IO 或网络的鸿蒙 App 中，它都值得被加入 dependencies。

最佳实践：

1. UI 对齐：由于转换后的字符串长度不固定（如 “1 B” vs “100.23 MB”），在列表显示时，建议使用 Monospaced (等宽) 字体或者右对齐，以保证视觉整齐。
2. 国际化：注意该库输出是英文单位（KB, MB）。如果需要中文（“1.5 兆”），可能需要简单的 replace 或寻找支持 l10n 的库。

六、完整实战示例

import 'package:filesize/filesize.dart';

void main() {
  print('=== 基础用法 ===');
  print(filesize(1024)); // "1 KB"
  print(filesize(123456789)); // "117.74 MB"

  print('\n=== 中文本地化 ===');
  // 简单的本地化封装
  String formatSizeCN(int bytes) {
    String fs = filesize(bytes);
    return fs
      .replaceAll('KB', '千字节')
      .replaceAll('MB', '兆字节')
      .replaceAll('GB', '吉字节');
  }

  // 模拟从鸿蒙文件系统获取的大小
  int appCacheSize = 1048576 * 5; // 5MB
  print('当前缓存: ${formatSizeCN(appCacheSize)}'); // "5 兆字节"

  print('\n=== 实际场景：下载进度 ===');
  int total = 50000000;
  int downloaded = 25000000;
  
  print('下载进度: ${filesize(downloaded)} / ${filesize(total)}');
  // "23.84 MB / 47.68 MB"
}