《卡片添加至桌面》三、@ohos.file.storageStatistics使用指南

HarmonyOS ohos.file.storageStatistics应用空间统计使用指南摘要本文详细介绍 HarmonyOSohos.file.storageStatistics模块的使用方法涵盖存储容量统计 API 的属性说明、同步/异步调用方式、完整代码示例以及在桌面卡片中展示存储信息的实战方案。效果一、模块概述ohos.file.storageStatistics是 HarmonyOS 提供的存储空间统计模块属于kit.CoreFileKit用于查询设备的总存储空间、可用空间和已用空间。支持同步和异步两种调用方式适用于存储信息展示、空间清理提醒等场景。1.1 适用场景设备存储信息展示页桌面卡片Widget显示存储使用情况存储空间不足预警应用存储占用统计1.2 模块归属属性值模块名ohos.file.storageStatisticsKitkit.CoreFileKit引入方式import { storageStatistics } from kit.CoreFileKit二、核心 API 详解2.1 属性与同步方法API类型说明返回值totalSize属性设备总存储容量字节numberfreeSize属性可用存储容量字节numbergetTotalSizeSync()方法同步获取总存储容量字节numbergetFreeSizeSync()方法同步获取可用存储容量字节number2.2 异步方法API说明返回值getTotalSize()异步获取总存储容量PromisenumbergetFreeSize()异步获取可用存储容量Promisenumber2.3 单位换算存储 API 返回值的单位为字节Byte常见换算方式constKB1024;constMB1024*KB;constGB1024*MB;constTB1024*GB;// 字节转 GBfunctionbytesToGB(bytes:number):number{returnbytes/(1024*1024*1024);}三、权限说明storageStatistics模块的基础属性和方法无需额外权限。但涉及应用级存储统计的高级 API 可能需要对应权限。四、基础示例存储空间信息展示4.1 创建项目使用 DevEco Studio 新建 ArkTS 项目选择Empty Ability模板。4.2 同步方式获取存储信息在entry/src/main/ets/pages/Index.ets中编写如下代码import{storageStatistics}fromkit.CoreFileKit;EntryComponentstruct StorageInfoDemo{StatetotalGB:number0;StatefreeGB:number0;StateusedGB:number0;StateusedPercent:number0;aboutToAppear():void{this.refreshStorageInfo();}refreshStorageInfo():void{// 同步获取存储信息单位字节lettotalBytesstorageStatistics.getTotalSizeSync();letfreeBytesstorageStatistics.getFreeSizeSync();// 转换为 GBthis.totalGBtotalBytes/(1024*1024*1024);this.freeGBfreeBytes/(1024*1024*1024);this.usedGBthis.totalGB-this.freeGB;this.usedPercentMath.round((this.usedGB/this.totalGB)*100);}// 根据使用率返回颜色getStorageColor():string{if(this.usedPercent90){return#E84026;// 红色 - 存储几乎满了}elseif(this.usedPercent70){return#FFB74D;// 橙色 - 存储较高}return#4FC3F7;// 蓝色 - 存储充足}build(){Column({space:20}){Text(存储空间信息).fontSize(24).fontWeight(FontWeight.Bold)Column({space:16}){// 已用存储量Text(${this.usedGB.toFixed(1)}GB).fontSize(36).fontWeight(FontWeight.Bold).fontColor(this.getStorageColor())Text(已使用${this.usedPercent}% / 共${this.totalGB.toFixed(1)}GB).fontSize(14).fontColor(#666666)// 存储进度条Progress({value:this.usedGB,total:this.totalGB,type:ProgressType.Linear}).width(80%).height(12).color(this.getStorageColor()).backgroundColor(#E0E0E0)// 详细信息Row(){Column({space:4}){Text(已用空间).fontSize(12).fontColor(#999999)Text(${this.usedGB.toFixed(2)}GB).fontSize(16).fontWeight(FontWeight.Medium)}.layoutWeight(1)Column({space:4}){Text(可用空间).fontSize(12).fontColor(#999999)Text(${this.freeGB.toFixed(2)}GB).fontSize(16).fontWeight(FontWeight.Medium)}.layoutWeight(1)Column({space:4}){Text(总容量).fontSize(12).fontColor(#999999)Text(${this.totalGB.toFixed(2)}GB).fontSize(16).fontWeight(FontWeight.Medium)}.layoutWeight(1)}.width(100%).justifyContent(FlexAlign.SpaceEvenly)}.width(90%).padding(24).backgroundColor(Color.White).borderRadius(16).shadow({radius:8,color:#1A000000,offsetY:4})Button(刷新).fontSize(16).width(60%).onClick((){this.refreshStorageInfo();})}.width(100%).height(100%).justifyContent(FlexAlign.Center).backgroundColor(#F5F5F5)}}4.3 异步方式获取存储信息asyncrefreshStorageInfoAsync():Promisevoid{try{// 异步获取存储信息lettotalBytesawaitstorageStatistics.getTotalSize();letfreeBytesawaitstorageStatistics.getFreeSize();this.totalGBtotalBytes/(1024*1024*1024);this.freeGBfreeBytes/(1024*1024*1024);this.usedGBthis.totalGB-this.freeGB;this.usedPercentMath.round((this.usedGB/this.totalGB)*100);}catch(error){console.error(获取存储信息失败:${JSON.stringify(error)});}}4.4 同步 vs 异步对比方式优点缺点推荐场景同步getTotalSizeSync()代码简洁无需 async/await可能阻塞主线程快速展示数据量小异步getTotalSize()不阻塞主线程需要 async/await复杂业务多接口并行五、进阶使用 Gauge 组件展示存储环形图HarmonyOS 提供了Gauge组件非常适合展示存储使用率的环形图效果import{storageStatistics}fromkit.CoreFileKit;EntryComponentstruct StorageGaugeDemo{StateusedGB:number0;StatetotalGB:number0;aboutToAppear():void{this.usedGB(storageStatistics.getTotalSizeSync()-storageStatistics.getFreeSizeSync())/(1024*1024*1024);this.totalGBstorageStatistics.getTotalSizeSync()/(1024*1024*1024);}build(){Column(){Gauge({value:this.usedGB,min:1,max:this.totalGB}){Column(){Text(${this.usedGB.toFixed(1)}).fontSize(32).fontWeight(FontWeight.Bold).fontColor(#333333)Text(总计${this.totalGB.toFixed(1)}GB).fontSize(12).fontColor(#999999)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}.value(this.usedGB).startAngle(210).endAngle(150).strokeWidth(24).width(200).height(200)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}六、在应用卡片中使用存储信息6.1 主应用端获取并保存import{storageStatistics}fromkit.CoreFileKit;import{preferences}fromkit.ArkData;// 获取存储信息lettotalGBstorageStatistics.getTotalSizeSync()/(1024*1024*1024);letfreeGBstorageStatistics.getFreeSizeSync()/(1024*1024*1024);letusedGBtotalGB-freeGB;letstorageInfo${usedGB.toFixed(1)}/${totalGB.toFixed(1)}GB;// 保存到 Preferencesletprefspreferences.getPreferencesSync(context,{name:myStore});prefs.putSync(totalStorageGB,totalGB);prefs.putSync(freeStorageGB,freeGB);prefs.putSync(usedStorageGB,usedGB);prefs.putSync(storageInfo,storageInfo);prefs.flush();6.2 卡片 UI 展示Componentstruct StorageWidgetCard{LocalStorageProp(usedStorageGB)usedGB:number0;LocalStorageProp(totalStorageGB)totalGB:number0;build(){Stack(){Gauge({value:this.usedGB,min:1,max:this.totalGB}){Column(){Text(${this.usedGB.toFixed(1)}).fontSize(20).fontWeight(FontWeight.Bold)Text(总计${this.totalGB.toFixed(1)}GB).fontSize(8).fontColor(rgba(0,0,0,0.6))}.justifyContent(FlexAlign.Center)}.startAngle(210).endAngle(150).strokeWidth(20)}.width(100%).height(100%)}}七、常见问题与注意事项7.1 返回值单位是什么所有存储容量 API 返回值的单位为字节Byte需要自行转换为 KB/MB/GB。7.2 同步方法是否会阻塞 UIgetTotalSizeSync()和getFreeSizeSync()为同步调用在大多数设备上响应很快。但如果需要频繁调用或在低端设备上使用建议使用异步版本。7.3 存储信息不准确系统存储会因缓存、临时文件等原因产生波动建议每次获取时重新计算避免使用缓存的旧数据。八、总结知识点内容模块导入import { storageStatistics } from kit.CoreFileKit获取总容量storageStatistics.getTotalSizeSync()(字节)获取可用容量storageStatistics.getFreeSizeSync()(字节)单位换算字节 ÷ (1024³) GB异步版本getTotalSize()/getFreeSize()权限要求基础属性无需额外权限UI 展示结合Gauge组件实现环形图掌握storageStatistics模块后配合batteryInfo和deviceInfo即可构建完整的设备信息展示应用和桌面卡片。