写在前面如果你写过鸿蒙 ArkUI 应用大概率遇到过这个场景你写个用户头像区Image 加载网络 URL——结果网慢时一片白加载失败也是一片白用户体验崩。你想「加个占位图」——查文档发现 Image 有.alt()设占位还有.onComplete()/.onError()事件。你点进去发现 API 一脸懵。你又想「资源图、本地图、网络图能不能用同一个 Image」——查文档发现 Image 源是ResourceStr统一类型四源都吃。这是「裸 Image 加载」和「Image 全流程」的分水岭。鸿蒙给的图片加载答案是 Image alt onComplete/onError——ResourceStr统一四源、.alt()设占位、.onComplete()监听加载完、.onError()监听失败。本文就用一个真机可跑的「网络源 资源源 本地源 alt 占位」demo把 Image 多源加载从「听名字一脸懵」讲到「下个项目直接抄」。代码托管在 AtomGit文末有链接真机实拍截图作证。这是组件深水区系列篇。适合人群写过鸿蒙应用、被「Image 加载失败一片白」折磨过的同学。不适合人群还在学State的同学——出门左转看我的入门篇。一、先讲清楚Image 多源加载到底是啥一句话Image 是鸿蒙图片展示组件ResourceStr 统一四源 alt 占位 onComplete/onError 全流程监听。你之前写前端img srcurl是浏览器宿主标签——鸿蒙不是浏览器环境没 HTML 标签。Image 是鸿蒙专门给图片展示的原生组件能力对标前端的imgonload/onerror但更精细可控。核心 API 一览API作用一句话理解Image(src: ResourceStr)创建 Image「src 是 ResourceStr 统一四源」.alt(占位图)加载失败占位「加载不出来时显示啥」.objectFit(ImageFit)缩放模式「Contain/Cover/Fill/Center」.onComplete(cb)加载完回调「拿到真实 w/h」.onError(cb)加载失败回调「失败时触发」记住这五个往下看。二、动手一个 Image 四源切换的 demo2.1 Image 基础网络源 alt 占位StateimgSrc:ResourceStrhttps://placehold.co/300x200/4CAF50/white?textNetworkImageImage(this.imgSrc).width(92%).height(180).objectFit(ImageFit.Contain).backgroundColor(#f5f5f5).borderRadius(8).alt($r(app.media.startIcon))// alt 加载失败占位.onComplete((e){constw:numbere?.width??0consth:numbere?.height??0this.logText加载完w${w}h${h}}).onError((){this.logText加载失败alt 占位})三个细节Image(src: ResourceStr)——src 是ResourceStr统一类型网络 URL / 资源 $r / 本地路径都吃.alt($r(app.media.startIcon))——加载失败时显示占位图资源源避免一片白.objectFit(ImageFit.Contain)——缩放模式Contain 保比例留白、Cover 铺满裁剪、Fill 拉伸、Center 原大小居中这是 Image 最核心的能力——一个 Image 组件吃四源alt 保底onComplete/onError 全流程可见。2.2 资源源$r 引用privateresSrc:ResourceStr$r(app.media.startIcon)Button(② 资源源$r app.media).onClick((){this.imgSrcthis.resSrcthis.sourceLabel资源源$r app.media.startIcon})资源源用$r(app.media.xxx)引用——图打包进 hap加载最快、不依赖网络。适合应用内固定图标/占位图。2.3 本地源沙箱路径privatelocalSrc:string/data/local/tmp/not-exist-demo.jpegButton(③ 本地源沙箱路径).onClick((){this.imgSrcthis.localSrcthis.sourceLabel本地源沙箱路径不存在触发 alt})本地源用沙箱路径字符串——应用沙箱内文件路径。demo 里故意写不存在的路径触发onError alt 占位。2.4 onComplete / onError全流程监听.onComplete((e){constw:numbere?.width??0consth:numbere?.height??0this.logText加载完w${w}h${h}}).onError((){this.logText加载失败alt 占位})onComplete回调给真实宽高{width, height}——注意 ArkTS 强约束e可能 undefined要e?.width ?? 0兜底。onError加载失败时触发此时 alt 占位图顶上。三、真机实拍网络源加载成功 本地源触发 alt我把这个 demo 補到真机上跑鸿蒙 6.1.1.125, API 24依次点②资源源 ③本地源下面两张都是真机实拍没有任何 P 图。网络源态当前源「网络源https URL」 图片区显示绿色 placehold.co 占位图网络加载成功 ①②③ 三按钮 日志区切到本地源后当前源「本地源沙箱路径不存在触发 alt」 图片区显示 startIcon 资源图alt 占位生效 日志区更新重点看第二张本地路径不存在 → 图片区显示 startIcon 资源图——.alt()占位真生效了onError 真触发了。这是 Image 全流程的真机证明。四、Image vs 前端img啥差异新手最容易纠结的问题既然前端img那么标准鸿蒙为啥要造 Image维度前端img鸿蒙Image运行环境浏览器宿主鸿蒙原生运行环境源类型url 字符串ResourceStr网络/资源/本地/沙箱占位图无原生要 CSS 替身.alt()原生支持加载完事件onload.onComplete()给真实 w/h失败事件onerror.onError()缩放模式CSSobject-fit.objectFit(ImageFit)一句话决策鸿蒙应用图片展示必须用 Image不能用img不存在。五、常见坑都是血泪坑症状解法Image src 用裸字符串期望资源加载失败资源源用$r(app.media.xxx)不是字符串忘了.alt()加载失败一片白.alt($r(...))设占位图onComplete的e直接用编译报「possibly undefined」e?.width ?? 0兜底网络图加载慢 UI 卡体验差网络图 alt 占位 异步加载.objectFit忘设图片拉伸变形按 Contain/Cover/Fill 选本地源路径写错加载失败沙箱路径要正确或用 alt 保底大图不限制 width/height内存炸Image 设固定 w/hobjectFit 缩放六、ResourceStr 四源速查源写法用途性能网络源https://...URL 字符串用户头像/动态图慢依赖网络资源源$r(app.media.xxx)应用内固定图标最快打包进 hap本地源沙箱路径字符串应用沙箱内文件快内存源PixelMap对象代码生成的图快七、完整代码仓库本文所有代码都已托管到AtomGit欢迎 clone、提 issue、点 star仓库地址https://atomgit.com/JaneConan/arkui-image仓库包含完整的「Image 四源切换 alt onComplete/onError」demo 工程Index.ets主页面网络源/资源源/本地源三按钮 alt 占位 加载事件可直接用 DevEco Studio 打开运行真机装普通应用必能跑八、下一步该学什么跑通这个 demo 之后你的鸿蒙图片加载就入门了。后续按这个顺序往下List Section 分组吸顶下一篇大列表分组 sticky 头Swiper 自动轮播轮播 Indicator 自动播放ScrollView 嵌套滚动Scroll 容器 嵌套滚动Slider 滑块控制滑块 onChange stepGrid 网格布局网格 GridLayout写在最后Image 的本质是**「鸿蒙给图片展示的原生组件ResourceStr 统一四源 alt 保底 onComplete/onError 全流程」**——不是前端img是鸿蒙专门给图片的原生组件。代价是.alt() 事件监听多写几行。一旦你开始用 Image 全流程思维写图片展示你会发现大部分「用户头像」「动态图」「固定图标」「加载失败保底」的需求都是 Image alt onComplete/onError 的自然结果。代码量比裸 Image 多三行体验可控性高九成。代码已经给你了仓库链接在上面。现在关掉这篇文章打开 DevEco Studio把 demo 蜜起来亲手点三源切换 看 alt 占位生效。跑通了回来评论区打个「1」我看看有多少人真的动手了。作者JaneConan仓库https://atomgit.com/JaneConan/arkui-image协议Apache-2.0随便用别告我