Flutter 鸿蒙插件适配实战：用 accurate_storage_info 0.1.1 查询总量、可用量与已用量

●VON

9人浏览 · 2026-09-13 12:46:21

●VON · 2026-09-13 12:46:21 发布

适配仓库： https://atomgit.com/oh-flutter/accurate_storage_info
适配 TAG： 尚未发布，当前请锁定受测提交

受测提交： ce80048b74d88f27e496049595bad58862946140

一、最终效果与适配目标

accurate_storage_info 0.1.1 返回整数 bytes，并提供总容量、用户可用容量和已用容量。它的业务语义更接近系统存储统计，而 disk_space_2 查询的是某个路径所在文件系统并返回 MiB。两个库不能只因为方法名相似就复用同一实现。

本次 OHOS 适配选择 storageStatistics.getTotalSize() 和 getFreeSize()。关键原因是系统存储服务的 free 表示用户可用容量；普通 statvfs 接口可能使用包含保留块的 f_bfree。文章如果只看函数名，不核对底层口径，很容易得到“能返回数字但语义错了”的实现。

在这里插入图片描述

图 1：真机宿主显示 total、available、used 与独立对照值。

验证点	实测结果	证据
总量、可用量和已用量	两轮返回安全整数，且都在合法范围	图 1、图 6
独立系统对照	与宿主直连 `storageStatistics` 的差值远小于 64 MiB 容差	图 6
非原子采样	已用量可因跨请求采样出现小幅变化	图 6、正文说明
自动化与构建	31 项 Dart/Widget/ArkTS 功能测试及 HAP 构建通过	图 4、图 5
验证边界	未将单台真机结果外推为其他系统版本或跨平台口径承诺	真机说明

成果速览

项目	内容
上游基线	`0.1.1` 对应提交 `52de791598c239e81cece2a6b86a37ea4e02b9b7`，MIT
适配分支	`feat/ohos_accurate_storage_info_0.1.1`
适配 TAG	尚未发布
真机受测提交	`ce80048b74d88f27e496049595bad58862946140`
当前远程 HEAD	`ce80048b74d88f27e496049595bad58862946140`
新增 OHOS 能力	读取系统 total/free bytes，计算 used，校验数值并隔离旧 Engine 回调
真机结论	两轮公开 API 与独立系统服务对照通过

二、环境

项目	实测值
Flutter OH	`3.41.10-ohos-1.0.1`
Dart	`3.11.5`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26；示例兼容 API 18，存储接口 API 15+
设备	CHZ-AL00，HarmonyOS `7.0.0.105(SP10C00E105R2P4)`
插件	`accurate_storage_info 0.1.1`

环境搭建直接使用 Flutter OH 指南。截至 2026 年 9 月 12 日，版本号最大的 Flutter OH 标签是预览版 3.44.9+ohos-0.0.1-canary1，最新正式稳定标签仍是本文完成构建和真机回归的 3.41.10-ohos-1.0.1。

三、仓库同步与版本基线

上游没有发布标签，0.1.1 基线提交为 52de791598c239e81cece2a6b86a37ea4e02b9b7。适配前核对最新发布包、MIT 许可证、清单及实时组织仓库，未发现同包名 OHOS 实现。AtomGit 仓库保留上游历史。

git clone https://atomgit.com/oh-flutter/accurate_storage_info.git
cd accurate_storage_info
git switch feat/ohos_accurate_storage_info_0.1.1
git branch --show-current

基线重建命令：

git switch -c feat/ohos_accurate_storage_info_0.1.1 52de791598c239e81cece2a6b86a37ea4e02b9b7
flutter create --template=plugin --platforms=ohos --no-pub .

插件模板只生成 OHOS 壳，不能替代存储口径分析。图 2 汇总了实际 AtomGit origin、适配分支和 HEAD，可核对仓库来源与当前分支状态。

在这里插入图片描述

图 2：AtomGit origin、适配分支与 HEAD。

四、原 API 与通道

公开入口保持静态方法和整数返回：

final total = await StorageInfo.getTotalBytes();
final available = await StorageInfo.getAvailableBytes();
final used = await StorageInfo.getUsedBytes();

真实通道是 dev.tanh/storage_info，方法名分别为 getTotalBytes、getAvailableBytes 和 getUsedBytes。仓库里另有未被公共 API 使用的模板 storage_info/getPlatformVersion，本次没有把它包装成已支持能力。

五、OHOS 存储统计实现

pubspec.yaml 注册 StorageInfoPlugin。每个请求同时发起 total 和 free 两次系统读取，再按方法返回：

const values = await Promise.all([
  Promise.resolve().then(() => storageStatistics.getTotalSize()),
  Promise.resolve().then(() => storageStatistics.getFreeSize()),
]);
const total = values[0];
const available = values[1];

switch (call.method) {
  case 'getTotalBytes':
    result.success(total);
    return;
  case 'getAvailableBytes':
    result.success(available);
    return;
  case 'getUsedBytes':
    result.success(total - available);
    return;
}

两次系统调用不是原子快照。每个 Dart 方法又会发起自己的新请求，所以分开调用得到的三项值不一定严格满足 total - available == used。后台写入可能正好发生在调用之间，测试应检查合法范围和近似关系，而不是逐字节相等。

实现拒绝非安全整数、total <= 0、available < 0 或 available > total，错误码为 NO_STORAGE_DATA；系统异常为 STORAGE_QUERY_FAILED。满盘时 available 为 0 是合法值。generation 同样用于拦截跨 Engine 重绑的旧 Promise 结果。

返回值不在插件里换算单位。业务显示 GiB 时可以除以 1024 * 1024 * 1024，但原 API 始终是 bytes。

在这里插入图片描述

图 3：storageStatistics 总量/可用量查询、引擎代次与参数校验。

六、交付内容

分支保留原 lib/、Android/iOS 实现、MIT LICENSE 和上游历史，新增 OHOS HAR、示例工程、双语文档、14 项 Dart 测试、2 项 widget 测试、生产 ArkTS 测试与设备入口。示例同时显示 bytes 和 GiB，并支持失败后重试。

不引入 C++ 私有扩展，不申请存储权限，也不提交签名、SDK 路径、Node 依赖或构建产物。

七、测试、失败预检与构建

flutter pub get
flutter analyze
flutter test
npm install --prefix ohos/test --no-save --no-package-lock typescript@5.9.3
node --test ohos/test/storage_info.test.cjs
cd example
flutter test
flutter build hap --debug --no-codesign

14 项 Dart、2 项 widget、15 项生产 ArkTS 功能测试通过，共 31 项；另有 1 项重复回复夹具自检，不计入功能数。静态分析和无签名 HAP 构建通过。

原生测试最初发现“系统函数同步抛错，同时另一个 Promise 异步拒绝”时存在组合异常处理问题。实现改为用 Promise.resolve().then() 统一捕获同步与异步错误，再回归通过。失败预检日志单独保留，没有从记录中删除。

最终提交为 ce80048b74d88f27e496049595bad58862946140。

在这里插入图片描述

图 4：失败预检回归、31 项功能测试统计与 Flutter 复跑。

在这里插入图片描述

图 5：HAP 元数据、SHA-256 及远程依赖提交。

八、Demo 与真机验收

dependencies:
  accurate_storage_info:
    git:
      url: https://atomgit.com/oh-flutter/accurate_storage_info.git
      ref: ce80048b74d88f27e496049595bad58862946140

执行 flutter pub get 后应核对 pubspec.lock 中的 resolved-ref。当前没有 OHOS 适配 TAG，使用完整 SHA 可以确保业务项目与本文的构建、真机证据对应同一份代码。

隔离宿主通过远程 Git 固定到 ce80048b74d88f27e496049595bad58862946140，完成 pub get、签名 HAP 构建和覆盖安装。2026 年 9 月 11 日在 SP10 真机连续跑两轮：第一轮 total=128000000000、available=73951276210、used=54048723790；第二轮 total=128000000000、available=73950322433、used=54049681732。所有值均为安全整数，且满足 0 <= available, used <= total。

同一宿主又直接调用 storageStatistics 作独立对照。第一轮公开 API 可用量与前采样只差 -4165 bytes，used 减去 total - available 为 0；第二轮对应差值是 -4165 和 4165 bytes，远低于 64 MiB 容差。小波动来自跨调用的非原子采样，不是数值精度承诺；也不能把这组结果外推为 Android/iOS 口径完全一致。

在这里插入图片描述

图 6：两轮 total/available/used 与独立 storageStatistics 的实际差值。

应用内多状态补拍

在这里插入图片描述

图 7：accurate_storage_info 0.1.1 首次采样同时展示 GiB、原始 bytes、采样差值和读取耗时。

在这里插入图片描述

图 8：第 2 次采样中总容量不变，可用与已用 bytes 随系统活动小幅变化，且仍满足加和关系。

九、提交与远端

git status --short
git add pubspec.yaml ohos example test README.OpenHarmony.md README.OpenHarmony_CN.md
git commit -m "feat(ohos): adapt accurate_storage_info 0.1.1"
git push -u origin feat/ohos_accurate_storage_info_0.1.1

仓库已公开，适配分支为默认分支；2026 年 9 月 12 日匿名核对 HEAD 为 ce80048b74d88f27e496049595bad58862946140，与真机受测提交一致。

十、FAQ

Q1：为什么不用 statvfs.getFreeSize

现象： 两个 API 都叫 free，返回值却可能不同。
原因： 普通 statvfs 可能包含保留块，而本库要的是系统报告的用户可用容量。
解决方法： 使用 storageStatistics.getFreeSize() 并在文档中固定口径。
验证结果： 源码测试覆盖方法映射；真机两轮也与独立 storageStatistics 对照通过。

Q2：三次调用为何不满足严格减法

现象： total - available 与另一次 used 相差少量字节。
原因： 每个公开调用都重新读系统，且 total/free 本身也不是原子快照。
解决方法： 同一请求内计算 used，跨请求测试使用合理范围和记录波动。
验证结果： 自动化验证同次请求关系；真机实际差值最大 4165 bytes。

Q3：available 为 0 是错误吗

现象： 满盘设备可能返回 0。
原因： 0 表示用户没有可用空间，是合法状态。
解决方法： 只拒绝负数、不安全整数和 available 大于 total。
验证结果： 满盘与零使用量边界测试通过。

十一、总结

accurate_storage_info 已在 OHOS 端接入系统存储统计，按 bytes 返回 total、available 和同次采样计算出的 used。31 项功能测试、失败预检回归、静态检查和 HAP 构建已完成；SP10 真机的两轮公开 API 也与独立系统服务对照通过。文章仍保留非原子采样和跨平台口径不同的边界。