图片是App里最占资源的部分——一张高清图几MB列表里几十张图就是上百MB。不做缓存每次都从网络加载流量炸了、内存炸了、用户体验也炸了。HarmonyOS的Image组件有内置的内存缓存但磁盘缓存和预加载需要自己搞。这篇把图片缓存的完整策略讲清楚。Image组件的缓存机制Image组件默认开启内存缓存。同一个URL的图片只下载一次后续直接从内存读取Image(https://example.com/photo.jpg).width(200).height(200).objectFit(ImageFit.Cover)Image内部维护了一个LRU缓存池。缓存容量由系统控制开发者无法直接调整。图片组件销毁后缓存中的图片不会立即清除——只要还有内存空间下次加载同URL会命中缓存。缓存控制通过imageCacheSize调整缓存大小仅在特定版本支持Image(https://example.com/photo.jpg).width(200).height(200).autoResize(true)autoResizetrue默认会根据组件尺寸缩小解码后的图片。200x200的Image不会解码出4K的bitmap再缩放而是直接解码出200x200的图。这个属性对内存优化极其重要——不加的话每个Image组件都持有原始尺寸的bitmap内存很快就会爆。磁盘缓存Image组件的内置缓存只在内存中应用重启后缓存丢失。要做磁盘缓存需要手动实现import{http}fromkit.NetworkKit;import{fileIo}fromkit.CoreFileKit;import{common}fromkit.AbilityKit;classImageDiskCache{privatecontext:common.UIAbilityContext;privatecacheDir:string;constructor(context:common.UIAbilityContext){this.contextcontext;this.cacheDircontext.cacheDir/image_cache;if(!fileIo.accessSync(this.cacheDir)){fileIo.mkdirSync(this.cacheDir);}}privateurlToKey(url:string):string{lethash0;for(leti0;iurl.length;i){hash((hash5)-hash)url.charCodeAt(i);hashhashhash;}returnMath.abs(hash).toString(16);}asyncget(url:string):Promisestring|null{letkeythis.urlToKey(url);letfilePaththis.cacheDir/key;if(fileIo.accessSync(filePath)){returnfilePath;}returnnull;}asyncput(url:string):Promisestring{letkeythis.urlToKey(url);letfilePaththis.cacheDir/key;if(fileIo.accessSync(filePath)){returnfilePath;}lethttpRequesthttp.createHttp();letresponseawaithttpRequest.request(url,{method:http.RequestMethod.GET,expectDataType:http.HttpDataType.ARRAY_BUFFER});httpRequest.destroy();if(response.responseCode200response.resultinstanceofArrayBuffer){letfilefileIo.openSync(filePath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY);fileIo.writeSync(file.fd,response.result);fileIo.closeSync(file.fd);returnfilePath;}returnurl;}}urlToKey把URL转成短文件名——URL太长不能直接当文件名。用简单的hash算法生成唯一key。注意这个hash不是加密hash存在碰撞可能。生产环境建议用SHA-256但ArkTS里需要用cryptoFramework模块。简单场景用这个足够了。缓存优先加载先查缓存缓存没有再下载StateimageSrc:string|Resource$r(app.media.placeholder)asyncloadImage(url:string):Promisevoid{letcachedPathawaitthis.diskCache.get(url);if(cachedPath!null){this.imageSrcfile://cachedPath;}else{this.imageSrcurl;letlocalPathawaitthis.diskCache.put(url);}}缓存命中时用file://协议加载本地文件未命中时先用URL加载Image组件会自动下载同时在后台存入磁盘缓存。问题这段代码有竞态条件。如果缓存还没写完用户就退出页面了put操作可能写到一半。解决方式是加锁或者不等待put完成后台写入asyncloadImage(url:string):Promisevoid{letcachedPathawaitthis.diskCache.get(url);if(cachedPath!null){this.imageSrcfile://cachedPath;}else{this.imageSrcurl;this.diskCache.put(url).catch((){});}}catch静默处理写入失败——图片已经显示了缓存写入失败不影响UI。预加载预加载是提前下载图片等用户真正看到时直接从缓存读取。适用场景分页列表下一页的图片、轮播下一张图、详情页的图片。classImagePreloader{privatediskCache:ImageDiskCache;privatepreloadQueue:string[][];privateisPreloading:booleanfalse;constructor(diskCache:ImageDiskCache){this.diskCachediskCache;}enqueue(urls:string[]):void{for(leti0;iurls.length;i){if(this.preloadQueue.indexOf(urls[i])0){this.preloadQueue.push(urls[i]);}}this.processQueue();}privateasyncprocessQueue():Promisevoid{if(this.isPreloading||this.preloadQueue.length0){return;}this.isPreloadingtrue;while(this.preloadQueue.length0){leturlthis.preloadQueue.shift();if(url!undefined){letcachedawaitthis.diskCache.get(url);if(cachednull){awaitthis.diskCache.put(url);}}}this.isPreloadingfalse;}}预加载队列串行执行——同时下载多张图会占满带宽影响当前页面的图片加载。一张下载完再下下一张。使用// 列表加载第一页后预加载第二页的图片aboutToAppear():void{this.loadPage(1).then((){letnextPageUrlsthis.getPageImageUrls(2);this.preloader.enqueue(nextPageUrls);});}内存缓存管理大量图片列表需要控制内存使用。几个策略autoResizeImage组件默认开启按组件尺寸解码列表缓存控制LazyForEach的cachedCount控制预渲染项数List(){LazyForEach(this.dataSource,(item:DataItem){ListItem(){Image(item.coverUrl).width(100%).height(200).objectFit(ImageFit.Cover).autoResize(true)}},(item:DataItem)item.id)}.cachedCount(3)cachedCount3表示屏幕外额外缓存3个ListItem。超过3个的会被回收Image的bitmap也会释放。缩略图策略列表用小图详情用大图// 列表用缩略图URLImage(item.thumbUrl).width(120).height(80)// 详情用原图URLImage(item.originalUrl).width(100%)后端通常提供不同尺寸的图片——缩略图50KB原图2MB。列表只加载缩略图点击进详情才加载原图。缓存清理磁盘缓存不能无限增长。定期清理classImageDiskCache{privatemaxCacheSize:number50*1024*1024;// 50MBcleanIfNeeded():void{lettotalSizethis.getCacheSize();if(totalSizethis.maxCacheSize){this.cleanOldest(totalSize-this.maxCacheSize);}}privategetCacheSize():number{lettotalSize0;letfilesfileIo.listFileSync(this.cacheDir);for(leti0;ifiles.length;i){letstatfileIo.statSync(this.cacheDir/files[i]);totalSizestat.size;}returntotalSize;}privatecleanOldest(targetBytes:number):void{letfilesfileIo.listFileSync(this.cacheDir);letfileInfos:{name:string;time:number;size:number}[][];for(leti0;ifiles.length;i){letstatfileIo.statSync(this.cacheDir/files[i]);fileInfos.push({name:files[i],time:stat.mtime,size:stat.size});}fileInfos.sort((a,b)a.time-b.time);letfreed0;for(leti0;ifileInfos.lengthfreedtargetBytes;i){fileIo.unlinkSync(this.cacheDir/fileInfos[i].name);freedfileInfos[i].size;}}}超过50MB时按修改时间从旧到新删除直到总大小降到50MB以下。这就是简易的LRU磁盘缓存。在aboutToAppear中调用cleanIfNeeded每次打开应用时检查一次。占位图与错误图加载中的占位图和加载失败的错误图Image(item.coverUrl).width(120).height(80).objectFit(ImageFit.Cover).alt($r(app.media.image_placeholder)).onError((){this.failedImages.add(item.id);this.failedImagesnewSet(this.failedImages);})alt是加载中的占位图图片下载完成前显示。onError在加载失败时触发。加载失败时显示错误图if(this.failedImages.has(item.id)){Image($r(app.media.image_error)).width(120).height(80)}else{Image(item.coverUrl).width(120).height(80).alt($r(app.media.image_placeholder)).onError((){this.failedImages.add(item.id);this.failedImagesnewSet(this.failedImages);})}失败后替换为错误图。点击错误图可以重试Image($r(app.media.image_error)).onClick((){this.failedImages.delete(item.id);this.failedImagesnewSet(this.failedImages);})渐显动画图片加载完成时从透明渐显避免突然蹦出StateimageOpacity:number0Image(item.coverUrl).width(120).height(80).opacity(this.imageOpacity).onComplete((){animateTo({duration:300},(){this.imageOpacity1;});})onComplete在图片解码完成时触发animateTo驱动opacity从0到1的渐显。问题如果每个列表项都有独立的imageOpacity需要用数组或Map管理。更简单的做法是用renderGroupanimationImage(item.coverUrl).width(120).height(80).opacity(0.99).animation({duration:300,curve:Curve.EaseOut})opacity 0.99几乎看不出差异但会在图片从alt切换到实际图片时触发animation过渡。这个hack不需要State变量。踩坑清单问题原因解决列表滚动卡顿Image没开autoResizeautoResize(true)图片内存爆了加载了原图而非缩略图列表用thumbUrl重启后图片重新加载没有磁盘缓存实现diskCache缓存越来越大没有清理策略定期按LRU清理预加载影响当前加载并发下载占满带宽预加载串行队列加载失败无反馈没处理onError显示错误图重试图片突然出现没有渐显opacityanimation缓存文件名冲突hash碰撞用更长的hash或SHA-256file://协议加载失败路径不正确确认cacheDir路径cachedCount太大预渲染太多项cachedCount3~5图片缓存的核心策略内存缓存靠autoResizecachedCount磁盘缓存靠手写LRU预加载靠串行队列展示靠占位图渐显。不做这四件事图片列表的体验永远是加载中→突然出现→偶尔白图。
