Image 组件加载与缓存：从一张图到流畅图库

本文基于 HarmonyOS（ArkTS 声明式开发范式，API 12 / 5.0.0）写作，所有示例均可在 DevEco Studio 模拟器中验证。配套演示工程位于本文同级目录 ohos/，包含完整可运行的 EntryAbility.ets 与 Index.ets。

一、引言

文字负责"说什么"，图片负责"看到什么"。在移动应用里，图片的占比往往超出直觉：电商的货架、社交的头像、资讯的封面、设置的图标，几乎每一屏都被图片填满。一个界面漂不漂亮，图片加载顺不顺，直接影响用户对"卡不卡、专不专业"的判断。

Image 是 ArkUI 里承载图片的基础组件。它表面简单——给个地址就能显示，但真正用好它，要跨过四道坎：第一，图片从哪里来（资源、本地文件、网络、内存像素）；第二，图片怎么塞进容器（缩放与裁剪）；第三，加载失败或缓慢时怎么办（占位与错误兜底）；第四，列表里几十上百张图时如何不卡（缓存与性能）。

很多团队在图片上踩过的坑，几乎都能归到这四类：图标用了网络地址导致离线白屏、大图直接缩显示撑爆内存、列表滑动掉帧、重复加载同一张图浪费流量。本文把这四道坎逐一拆开，并给出可运行的工程代码。读完之后，你应该能在大多数场景里——封面、头像、缩略图、图集——直接选出对的写法，而不是等上线后被用户反馈"图怎么半天不出来"。

从架构看，Image 在底层走的是解码-缓存-绘制三段式管线：先把原始数据（PNG/JPEG/WebP 等）解码成 GPU 可用的位图，再按缓存策略决定是否复用，最后交给渲染引擎按 objectFit 绘制。理解这条管线，后面讲缓存和性能时就不会觉得是"玄学"。

进一步说，图片和文字在渲染层面的地位并不对称。文字由字体引擎逐字成形，体积小、可复制、可被无障碍服务朗读；图片则是二进制位图，解码开销大、无法被朗读、对内存友好程度高度依赖尺寸。正是这种不对称，决定了我们在架构选型时要给图片单独留出一整套管理策略——加载、缓存、裁剪、回收，缺一不可。一个合格的鸿蒙开发者，不应只在"显示图片"这一步下功夫，而要向前看到资源从哪里来、向后看到它如何被回收，这样才能在业务膨胀时不至于被图片拖垮。

1.1 为什么图片值得单独写成一篇

把图片单列成章，不是因为它 API 多，而是因为它的"失败成本"高。一行文字写错，至多是错别字；一张图加载失败，用户看到的是刺眼的白块或裂图，对产品信任度的打击立竿见影。更隐蔽的是性能：一张 4000×3000 的手机照片，未经压缩直接解码进内存，按 ARGB 四字节每像素计算，占用约为：

[
4000 \times 3000 \times 4 \approx 48,\text{MB}
]

如果列表里同时涌进十几张这样的图，内存瞬间突破数百兆，系统直接触发回收甚至闪退。所以图片组件背后，其实是"内存、流量、体验"三者的平衡术。本文讲的所有技巧，归根结底都是在帮你做这道平衡题。

1.2 阅读路线图

本文按"由浅入深、由静到动"的顺序展开：

1. 先建立环境，把工程跑起来；
2. 再拆构造参数，弄清图片有哪几种来源；
3. 接着讲 objectFit，解决"图怎么放进去"；
4. 然后补占位与错误，解决"图出不来怎么办"；
5. 再深入缓存，理解"为什么第二次更快"；
6. 最后落到性能，把单张图的能力放大到成百上千张的列表场景。

如果你时间有限，至少读完第三节与第六节——前者是地基，后者是避坑清单。

1.3 质量与体积的权衡：没有免费的清晰

讨论图片绕不开一个永恒矛盾：用户想要清晰，开发者想要小巧。清晰度由分辨率和压缩质量决定，体积则由这两者共同决定，三者之间存在着此消彼长的关系。用一张表把常见选择的代价摆出来，会比凭感觉调参更靠谱：

经验上，同样一张照片，WebP 往往比 JPEG 再小三分之一左右，比 PNG 小得更多。所以除非你需要 PNG 的"无损"或特定兼容性，否则 WebP 是 newer 项目里的最优默认项。但也要提醒：格式省的是"传输与存储"，省不了"解码内存"——一张 4000×3000 的 WebP，解码后照样占约 48MB。所以"选对格式"和"控制分辨率"是两件事，前者管流量，后者管内存，谁也替不了谁。写图片逻辑时，脑子里要同时转这两本账。

1.4 图片与无障碍：被忽视的一半用户

讲图片离不开"无障碍"这个常被跳过的话题。文字可以被屏幕朗读（Screen Reader）读出来，图片默认不行。当视障用户用读屏软件浏览你的应用时，一张没有语义标注的图，在他们耳里就是一片沉默。ArkUI 提供了 accessibilityDescription 与 accessibilityText 来补这块短板：

Image($r('app.media.banner'))
  .width('100%').height(180)
  .accessibilityDescription('春节活动主视觉，含满减优惠信息')

这行代码不改变任何视觉表现，却能让读屏软件把图片"翻译"成一句话。很多团队在验收时只看眼睛，不看读屏，结果无障碍验收一票否决。把"给关键图加描述"写进组件规范，成本和收益完全不成正比——几乎零代价，却覆盖了相当比例的特殊用户。本文演示工程虽未逐个加描述，但在真实项目里，凡是承载信息的图都该补这一句。

二、环境准备

动手前先把环境理顺，避免卡在工具层面。

本文演示工程与仓库根目录的 Flutter 壳解耦，是一个独立 ArkTS 原生工程。关键点：网络图片必须声明权限，否则在真机/模拟器上会静默失败。权限写在 module.json5：

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" }
]

目录结构如下（与《001-Text 组件完全指南》保持一致）：

ohos/
├── AppScope/app.json5
├── build-profile.json5
└── entry/src/main/
    ├── module.json5
    └── ets/
        ├── entryability/EntryAbility.ets
        ├── pages/Index.ets
        └── components/*.ets

若你是在已有的 Flutter·鸿蒙壳工程里验证，只需关注 pages/Index.ets 与 components/ 下的组件；网络权限在原工程通常已具备，无需重复添加。

有一点必须提前澄清：本文是通用版（HarmonyOS 原生）文章，按模板约定使用模拟器验证即可；而项目里另一套 Flutter 鸿蒙专属模板明确指出"Flutter·鸿蒙不支持模拟器、须真机"。两者适用场景不同，请勿混用。当你站在原生 Image 视角时，模拟器完全够用，因为图片解码与缓存逻辑在模拟器和真机上一致，差异只在于 GPU 性能与网络环境。

另外提醒一句关于资源占位的事：演示工程引用了 $r('app.media.icon') 作为占位图与示例图，运行时需要在 entry/src/main/resources/base/media/ 下放入名为 icon.png 的文件；若想体验 rawfile 加载，还要在 resources/rawfile/ 放入 example.jpg。这些资源文件属于二进制，不随本文源码提供，读者按 README 说明自行准备即可。忽略这一步会在编译期报"资源不存在"，并非代码问题。

为了让你拿到工程后能"按图索骥"，把每个关键文件的职责逐一列清，避免打开工程后不知从哪看起：

这套结构刻意做得"薄入口、厚组件"：入口只做加载，业务逻辑全在 components/ 里，彼此不互相依赖。你日后写自己的图片模块时，完全可以照抄这个骨架——把 Index.ets 当路由器，把每个功能点拆成一个组件，既好读也好测。

三、核心 API 与原理解析

3.1 图片来源：四种入口

Image 的构造参数决定了图片从哪来，这是最先要分清的：

// 1. 资源引用（打包进 apk/hap，离线可用）
Image($r('app.media.icon'))

// 2. 本地路径（rawfile 或沙箱路径）
Image('rawfile://example.jpg')

// 3. 网络地址（需 INTERNET 权限）
Image('https://example.com/banner.png')

// 4. 内存像素图 PixelMap（已解码，适合裁剪/编辑后回显）
Image(this.pixelMap)

初看四种来源似乎随便选都行，但背后有一条朴素原则：变化频率越低、越核心的图，越该往"本地"靠；变化越频繁、越个性化的图，才交给网络。理由很简单——本地图零延迟、零流量、零失败率，是把"确定性"给到用户；网络图灵活却要承担延迟、流量、失败三重风险。所以判断一张图该走哪种来源，先问自己"它多久变一次"：几乎不变的图标、品牌图，闭眼选 $r；随版本发布的大图、离线包，选 rawfile；天天变的头像、封面、UGC，才用网络 URL；而需要二次加工（裁剪、滤镜、标注）的，解码成 PixelMap 再回显最顺手。这条原则能帮你避开九成以上的"图怎么不显示"类低级故障。

四类来源的能力差异，用表格对齐：

一个常见误区：把应用图标、按钮图标也走网络加载。这会让离线、弱网时整片白屏，正确的做法是用 $r 资源，把变化频率低、体量小的图打包进应用。

顺着资源来源再多说一句：ArkUI 的资源目录支持限定词机制。同一个 icon.png，你可以放在 media/（默认）、media-ldpi/、media-mdpi/、media-xhdpi/ 等不同密度目录下，系统会根据设备屏幕密度自动选最合适的那张。这比"只放一张超清图让所有设备都缩放"更省内存、更清晰。具体密度与目录后缀的对应关系大致如下：

实践中，图标类小图交由限定词目录最省心；而网络图因为本就按需下载，通常服务端根据请求头里的设备信息直接下发对应分辨率，不走这套本地目录逻辑。两者是两套并行的"多分辨率"思路，理解它们分别在哪一层生效，才不会在排查"图怎么发虚"时找错方向。

3.2 缩放与裁剪：objectFit 是核心

图片原始尺寸几乎永远不等于容器尺寸，objectFit 决定两者如何对齐：

Image($r('app.media.icon'))
  .width(100)
  .height(100)
  .objectFit(ImageFit.Cover)   // 填满并裁剪溢出部分

五种取值对照：

选型经验：头像、封面用 Cover（保证填满不变形）；展示完整图用 Contain（保证不裁切）；绝大多数列表缩略图都该避开 Fill，因为它会拉伸变形。None 和 ScaleDown 用得少，主要在需要"原样呈现"或"不放大只缩小"的场合。

为了把选型讲得更可操作，可以引入一个判断流程：先看业务是否允许裁掉图片边缘，再看是否允许留白，最后看是否容忍变形。三者优先级通常是"不变形 > 不裁切 > 不留白"，因为变形最伤观感，裁切次之，留白最可接受。

顺带纠正一个常见误解：objectFit 只决定"图片如何适配已经给定的容器尺寸"，它不会改变图片本身的分辨率，也不会减少解码后的内存占用。也就是说，一张 4000×3000 的图，即便用 Contain 显示成 100×100，解码时该占的 48MB 内存一点都少不了。真正省内存的办法，是让服务端下发小图，或用 ImageFit 配合采样。把这层关系想清楚，才不会把"显示变小"误当成"内存变小"。

再举两个真实的误用场景，帮你把规则记牢。场景甲：产品要一个"不被裁切的商品全貌图"，开发者顺手写了 Cover，结果图片上下被切，用户看不到鞋底款式，引发退货咨询。正确写法是 Contain，宁可留白也要保全。场景乙：聊天表情包要铺满气泡，开发者写了 Contain，结果小图被缩在中间四周发空，正确写法是 Cover 或 Fill（表情本就是方形，拉伸无所谓）。可见没有绝对"最好"的 fit，只有"最贴合业务意图"的 fit——先问业务要什么，再选枚举，而不是凭习惯默认 Cover。

3.3 占位与错误：alt / onComplete / onError

图片不是瞬间出现的，弱网时尤其慢。良好的体验要有"加载中"和"加载失败"两种兜底：

Image('https://example.com/banner.png')
  .width(160).height(120)
  .alt($r('app.media.icon') as Resource)   // 加载中占位
  .onComplete((msg: ImageCompleteMessage) => {
    // msg.width / msg.height / msg.componentWidth ...
  })
  .onError(() => {
    // 解码失败或地址不可达
  })

三者职责：

• alt：加载完成前显示的占位图，避免空白闪烁；
• onComplete：拿到解码后的真实宽高与状态码，可用于埋点；
• onError：失败兜底，可切默认图、弹提示、上报监控。

注意 alt 只在图片数据未就绪时生效；如果地址本身 404，onError 才会触发。两者配合才能覆盖"慢"和"错"两种情况。

把这三个回调串起来，其实就是一张图片从"发出请求"到"最终呈现"的状态机。把状态想清楚，你写出来的加载逻辑才不会在边界情况下抽风：

值得单独提的是"重试"这条边。弱网环境下，一次 onError 不代表永久失败，很多团队会在 onError 里加一个有限次数的重试（比如最多两次，间隔递增），既提升成功率，又不会无限重试耗尽流量。但重试一定要带上限，否则用户在地铁里打开页面，图片在后台疯狂重试，电量和流量都会被拖垮。状态机的价值，就是让你在写逻辑前先想清"还有哪些出口"，而不是等到线上报错才补。

3.4 缓存机制：三级管线

Image 默认开启缓存，理解它的层级能解释很多现象——为什么第二次打开更快、为什么冷启动还能看到图：

三级缓存的特征：

一个实用技巧：对强实时性图片（如带验证码、带时间戳的占位），可在 URL 加随机参数绕过缓存：

[
\text{url}’ = \text{url} + ‘?t=’ + \lfloor \text{now} \rfloor
]

这样每次都是新请求，避免看到旧图。

需要强调的是，缓存不是无限大的。内存缓存受系统可用内存约束，磁盘缓存也有配额上限。当容量触顶，系统会按策略（通常是最久未使用优先）淘汰旧条目。这意味着一个经验法则：缓存能加速"重复访问"，但救不了"海量不重复的大图"。如果一屏里全是不同 URL 的高清大图，缓存命中率接近于零，此时真正的优化点回到"减小单图体积"与"控制同时解码数量"上。

可以用命中率粗略评估缓存价值：

[
\text{HitRate} = \frac{N_{\text{hit}}}{N_{\text{total}}}
]

当 HitRate 长期偏低（比如低于 0.2），说明缓存形同虚设，应优先排查：是否每张图 URL 都带了随机参数、是否图片尺寸过大、是否列表滑动时频繁创建新 URL。反之，头像、图标这类"少量且高频"的资源，命中率天然接近 1，缓存收益最大。理解这个指标，你就能用数据而非感觉来判断缓存是否生效。

3.5 与其他组件的关系

Image 不是孤立的，它的近亲与边界：

选型一句话：静态展示用 Image，图文混排用 ImageSpan，需要逐帧或自定义绘制才上 Canvas/XComponent。

3.6 选型决策表：对着场景选组件

把"选哪个组件"这件事做成一张可直接查的决策表，比背规则更实用。遇到图片需求时，先回答下面几个问题，顺着走就能落到正确组件：

对应到具体决策，整理成表：

最容易踩的坑是"什么都用 Image + Stack 叠按钮"来模拟可点图片。这种做法在简单场景能跑，但一旦图片要换行、要随文本流动，就会破绽百出。规则其实很简单：图片本身不承载交互语义时，Image 足够；交互要绑定到图片的某个区域，老老实实上支持富文本交互的组件。

四、完整代码实现

演示工程以 Tabs 组织五个模块，每个模块对应前文讲的一类能力。这样拆分有两个好处：一是读者可以单独运行某个 Tab 验证某一知识点，不必被其他逻辑干扰；二是工程结构清晰，后续往里加新场景时只需新增一个组件并在 Index.ets 注册一个 TabContent。下面给出完整可运行代码，建议对照 ohos/entry/src/main/ets/ 下的同名文件阅读。

在动手抄代码前，先说清楚几个工程层面的约定：EntryAbility 只负责把窗口内容指向 pages/Index，不做任何图片逻辑，保持入口干净；所有图片相关的状态（如加载状态、命中计数）都收敛在各演示组件内部，用 @State 驱动 UI，符合声明式"状态即真相"的思路；组件之间不共享图片数据，避免无谓的耦合。这种"入口薄、组件厚"的划分，是 ArkUI 工程里值得养成的习惯。

4.1 入口：EntryAbility.ets

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  private readonly TAG: string = 'ImageGuideAbility';

  onCreate(want: object, launchParam: object): void {
    hilog.info(0x0000, this.TAG, '%{public}s', 'Ability onCreate');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, this.TAG, 'Failed to load: %{public}s', JSON.stringify(err));
        return;
      }
      hilog.info(0x0000, this.TAG, '%{public}s', 'Succeeded in loading the content.');
    });
  }

  onForeground(): void { hilog.info(0x0000, this.TAG, '%{public}s', 'onForeground'); }
  onBackground(): void { hilog.info(0x0000, this.TAG, '%{public}s', 'onBackground'); }
  onDestroy(): void { hilog.info(0x0000, this.TAG, '%{public}s', 'onDestroy'); }
  onWindowStageDestroy(): void { hilog.info(0x0000, this.TAG, '%{public}s', 'onWindowStageDestroy'); }
}

4.2 主页面：Index.ets

import { BasicImageDemo } from '../components/BasicImageDemo';
import { ImageFitDemo } from '../components/ImageFitDemo';
import { ImageStateDemo } from '../components/ImageStateDemo';
import { ImageCacheDemo } from '../components/ImageCacheDemo';
import { ImagePerformanceDemo } from '../components/ImagePerformanceDemo';

@Entry
@Component
struct Index {
  @State currentIndex: number = 0;

  build() {
    Column() {
      Tabs({ index: this.currentIndex }) {
        TabContent() { BasicImageDemo() }.tabBar('基础加载')
        TabContent() { ImageFitDemo() }.tabBar('缩放与裁剪')
        TabContent() { ImageStateDemo() }.tabBar('占位与错误')
        TabContent() { ImageCacheDemo() }.tabBar('缓存机制')
        TabContent() { ImagePerformanceDemo() }.tabBar('性能建议')
      }
      .barMode(BarMode.Scrollable)
      .width('100%').height('100%')
    }
    .width('100%').height('100%')
  }
}

4.3 基础加载：BasicImageDemo.ets

@Component
export struct BasicImageDemo {
  build() {
    Scroll() {
      Column({ space: 12 }) {
        Image($r('app.media.icon') as Resource)
          .width(120).height(120).borderRadius(8).backgroundColor('#F2F2F2')
        Image('rawfile://example.jpg')
          .width(120).height(120).objectFit(ImageFit.Cover)
          .alt($r('app.media.icon') as Resource)
        Image('https://developer.huawei.com/consumer/cn/develop/resource/img/hero-banner.png')
          .width(160).height(90).objectFit(ImageFit.Cover).borderRadius(8)
          .onError(() => console.warn('[ImageGuide] 网络图加载失败'))
      }
      .width('100%').padding(16)
    }
    .width('100%').height('100%')
  }
}

4.4 缩放与裁剪：ImageFitDemo.ets

@Component
export struct ImageFitDemo {
  @State fit: ImageFit = ImageFit.Cover;

  build() {
    Scroll() {
      Column({ space: 12 }) {
        Row({ space: 12 }) {
          Image($r('app.media.icon') as Resource).width(100).height(100).objectFit(ImageFit.None)
            .border({ width: 1, color: '#CCCCCC' })
          Image($r('app.media.icon') as Resource).width(100).height(100).objectFit(ImageFit.Contain)
            .border({ width: 1, color: '#CCCCCC' })
          Image($r('app.media.icon') as Resource).width(100).height(100).objectFit(ImageFit.Cover)
            .border({ width: 1, color: '#CCCCCC' })
          Image($r('app.media.icon') as Resource).width(100).height(100).objectFit(ImageFit.Fill)
            .border({ width: 1, color: '#CCCCCC' })
          Image($r('app.media.icon') as Resource).width(100).height(100).objectFit(ImageFit.ScaleDown)
            .border({ width: 1, color: '#CCCCCC' })
        }.width('100%').wrapContent()

        Image($r('app.media.icon') as Resource)
          .width(200).height(200).objectFit(this.fit)
          .borderRadius(8).border({ width: 1, color: '#CCCCCC' })
        Button('切换 Cover / Contain')
          .onClick(() => {
            this.fit = this.fit === ImageFit.Cover ? ImageFit.Contain : ImageFit.Cover;
          })
      }
      .width('100%').padding(16)
    }
    .width('100%').height('100%')
  }
}

4.5 占位与错误：ImageStateDemo.ets

import { promptAction } from '@kit.ArkUI';

@Component
export struct ImageStateDemo {
  @State status: string = '等待加载';
  @State errMsg: string = '';

  build() {
    Scroll() {
      Column({ space: 16 }) {
        Image('https://example.com/slow-image.png')
          .width(160).height(120).objectFit(ImageFit.Cover)
          .alt($r('app.media.icon') as Resource).borderRadius(8)

        Text(`当前状态：${this.status}`).fontSize(16).fontColor('#333333').width('90%')
        Text(this.errMsg).fontSize(14).fontColor('#FF4500').width('90%')

        Image('https://example.com/not-exist.png')
          .width(160).height(120).objectFit(ImageFit.Cover)
          .alt($r('app.media.icon') as Resource).borderRadius(8)
          .onComplete((msg: ImageCompleteMessage) => {
            this.status = `加载完成，尺寸 ${msg.width}x${msg.height}`;
          })
          .onError(() => {
            this.status = '加载失败';
            this.errMsg = 'onError 触发：地址不可达或解码失败';
            promptAction.showToast({ message: '图片加载失败', duration: 1500 });
          })
      }
      .width('100%').padding(16)
    }
    .width('100%').height('100%')
  }
}

4.6 缓存机制：ImageCacheDemo.ets

import { promptAction } from '@kit.ArkUI';

@Component
export struct ImageCacheDemo {
  @State hitCount: number = 0;
  private readonly url: string =
    'https://developer.huawei.com/consumer/cn/develop/resource/img/hero-banner.png';

  build() {
    Scroll() {
      Column({ space: 16 }) {
        Row({ space: 12 }) {
          Image(this.url).width(150).height(90).objectFit(ImageFit.Cover).borderRadius(8)
          Image(this.url).width(150).height(90).objectFit(ImageFit.Cover).borderRadius(8)
        }.width('100%')

        Text(`模拟命中次数：${this.hitCount}`).fontSize(16).fontColor('#0A59F7')
        Button('模拟再次访问（命中缓存）')
          .onClick(() => {
            this.hitCount += 1;
            promptAction.showToast({ message: `第 ${this.hitCount} 次访问，命中缓存`, duration: 1500 });
          })

        Column({ space: 6 }) {
          Text('1. 内存缓存：解码后的 PixelMap，命中最快')
          Text('2. 磁盘缓存：已下载编码数据，跨页面有效')
          Text('3. 网络：缓存未命中时回源')
        }.alignItems(HorizontalAlign.Start).width('90%')
      }
      .width('100%').padding(16)
    }
    .width('100%').height('100%')
  }
}

4.7 性能建议：ImagePerformanceDemo.ets

@Component
export struct ImagePerformanceDemo {
  private readonly urls: string[] = [
    'https://example.com/p1.png', 'https://example.com/p2.png',
    'https://example.com/p3.png', 'https://example.com/p4.png',
    'https://example.com/p5.png', 'https://example.com/p6.png'
  ];

  build() {
    Scroll() {
      Column({ space: 16 }) {
        List({ space: 8 }) {
          ForEach(this.urls, (url: string, idx: number) => {
            ListItem() {
              Row({ space: 12 }) {
                Image(url)
                  .width(80).height(80).objectFit(ImageFit.Cover)
                  .borderRadius(8).alt($r('app.media.icon') as Resource)
                Text(`缩略图 ${idx + 1}`).fontSize(16).fontColor('#333333')
              }.width('100%').padding(8)
            }
          }, (url: string) => url)
        }
        .width('90%').height(320)
      }
      .width('100%').padding(16)
    }
    .width('100%').height('100%')
  }
}

4.8 模块配置要点

module.json5 中声明 EntryAbility、pages/Index 路由，以及 ohos.permission.INTERNET 权限；字符串与颜色资源放在 resources/base/element/。这些都和通用 ArkTS 工程一致。

4.9 场景化实战：一个健壮的头像组件

前面五个组件是"拆开练"，这里把它们合起来，写一个真实业务里常见的圆形头像组件，把来源选择、objectFit、占位、错误兜底一次性用上：

@Component
export struct AvatarView {
  private readonly fallback: Resource = $r('app.media.icon') as Resource;
  @State showError: boolean = false;

  build() {
    Stack() {
      if (this.showError) {
        // 出错时显示首字母占位，而不是裂图
        Text('U')
          .fontSize(28)
          .fontColor('#FFFFFF')
          .backgroundColor('#0A59F7')
          .width(64)
          .height(64)
          .borderRadius(32)
          .textAlign(TextAlign.Center)
      } else {
        Image(this.avatarUrl)
          .width(64)
          .height(64)
          .borderRadius(32)                 // 圆形裁剪
          .objectFit(ImageFit.Cover)        // 填满不变形
          .alt(this.fallback)               // 加载中占位
          .onError(() => { this.showError = true; })
      }
    }
  }

  private get avatarUrl(): string {
    // 真实场景从状态或参数传入，这里用占位地址
    return 'https://example.com/avatar.png';
  }
}

这段代码里藏着前文所有要点：用 Cover 保证头像不变形、用 borderRadius(32) 把正方形裁成圆、用 alt 顶住加载空白、用 onError 切到首字母兜底。它之所以"健壮"，不是因为 API 高级，而是因为每一步都替"图出不来"留了后路。写图片组件时，养成"先想失败、再写成功"的习惯，能省掉线上一大半的客诉。

五、模拟器运行与效果展示

5.1 编译运行步骤

1. 用 DevEco Studio 打开本文配套 ohos/ 目录；
2. 在 entry/src/main/resources/base/media/ 放入 icon.png；
3. 需要演示 rawfile 图片时，在 entry/src/main/resources/rawfile/ 放入 example.jpg；
4. 顶部选择 Phone 模拟器（或真机），点击 Run；
5. 应用启动后进入 Index，通过 Tab 切换五个演示。

5.2 各 Tab 的预期效果

图 1：基础加载。依次展示 $r 资源图、rawfile 本地图、网络图，以及解码为 PixelMap 的来源差异。

图 2：缓存机制。两张相同 URL 的 Image 并排，点击按钮模拟再次访问命中缓存。

5.3 交互验证

在"占位与错误"Tab 中，失败地址会触发 onError，状态文本变为"加载失败"并弹出 Toast；在"缓存机制"Tab 中，反复点击按钮，命中计数递增，直观体现缓存复用；在"性能建议"Tab 中，列表滑动应保持流畅，图片带 alt 占位不闪白。

5.4 模拟器与真机的图片差异

虽然本文用模拟器验证已足够，但有必要知道模拟器和真机在图片上的几处差别，免得"模拟器好好的，真机翻车"：

• 网络环境：模拟器走宿主机网络，真机走蜂窝或 Wi-Fi，弱网表现差异大，真机更该测 onError 与重试；
• GPU 性能：模拟器软渲染，解码与绘制偏慢，真机硬解码更快，性能数字不可直接套用；
• 屏幕密度：模拟器可自由设 dpi，真机密度固定，多分辨率资源（限定词目录）的效果要在真机上看才准；
• 磁盘缓存位置：两者缓存路径不同，清理缓存的方式也不同，排查"缓存没生效"时要分清环境。

一句话：模拟器负责把功能跑通，真机负责把体验校准。本文所有示例在模拟器验证通过后，上真机大概率一致；若有偏差，优先往上面四点排查。

六、调试与常见问题

问题 1：网络图片一直白屏，控制台无报错。
先确认 module.json5 是否声明 ohos.permission.INTERNET；模拟器还要检查网络是否可达。多数"静默失败"都是权限漏了。

问题 2：图片变形（被拉伸）。
几乎都是误用 objectFit(ImageFit.Fill)。头像、封面改回 Cover，完整展示改 Contain。

问题 3：列表滑动掉帧。
检查三件事：图片是否给了固定 width/height（否则加载完成触发重排）；是否大图缩显示（应让服务端下发缩略图）；列表是否配合 List 的懒加载。

问题 4：同样的图反复下载，没命中缓存。
确认没有给 URL 加随机参数；磁盘缓存在应用卸载后清空属正常行为。

问题 5：alt 占位没出现。
alt 仅在数据未就绪时生效。地址直接 404 时 onError 触发，可在回调里手动切默认图。

性能建议： 给每张 Image 显式尺寸以提前占位，避免布局抖动；服务端按显示尺寸下发缩略图，显著降低内存与流量；WebP 比 PNG/JPEG 更小；静态展示优先 Image，不要为"能画"而用 Canvas。

6.1 图片性能优化清单

把前面零散的建议收拢成一份可执行的清单，开发自测时逐项核对，能挡掉绝大多数图片问题：

这份清单的意义在于：图片性能不是某一项做对就行，而是"来源—尺寸—格式—缓存—回收"五环相扣。任何一环断掉，整体体验就会塌。比如你服务端下了小图（格式对），但列表没做懒加载（回收错），滚得快了照样卡；反过来懒加载做了，但每张图都加时间戳绕缓存（缓存错），流量又炸了。所以用清单而非单点思维去对待图片，才是工程化的做法。

6.2 一个容易忽略的细节：圆角与裁剪的代价

很多开发者喜欢用 borderRadius 做圆形头像，这没问题，但要明白它是在绘制阶段裁剪，不会改变解码内存。也就是说，圆形头像省的是"视觉上的方角"，不是"内存里的方图"。如果头像原图是 2000×2000，即便你只显示 64×64 且裁成圆，解码时依然按 2000×2000 占内存。正确姿势永远是：让服务端下发 128×128 左右的头像，本地再用 borderRadius 裁圆。把"显示尺寸"和"解码尺寸"区分开，是图片优化里最值钱的一条认知。

七、总结与扩展

7.1 进阶：大图采样与 PixelMap 解码

前文一直在用 Image(url) 让系统自动解码，这在绝大多数场景足够。但有一种情况必须自己动手：加载一张几千万像素的本地大图（比如相册原图、扫描件），直接丢给 Image 会瞬间吃掉上百兆内存。此时要用 @kit.ImageKit 做采样解码——不按原分辨率解码，而是先算一个缩放比，只解到目标尺寸。

采样比的计算逻辑是：目标尺寸除以原图尺寸，取较大边的比值作为 sampleSize 的基准。示意如下：

核心代码骨架（伪代码思路，真实 API 以 ImageKit 文档为准）：

import { image } from '@kit.ImageKit';

// 先拿到源信息，再决定采样率，避免一次性解码整张大图
const source = image.createImageSource(fd);
const info = await source.getImageInfo();
const ratio = Math.max(info.width / 1080, info.height / 1080);
const pixelMap = await source.createPixelMap({
  sampleSize: Math.ceil(ratio)   // 采样率越大，解码出的图越小
});
// 随后 Image(pixelMap) 显示，内存从数百兆降到几兆

这一步的收益用数字最直观：一张 6000×4000 的图，原样解码约 96MB；按 ratio=4 采样后，解码尺寸降到 1500×1000，内存降到约 6MB，足足缩小十六倍。在相册、大图预览这类场景，采样解码是绕不开的基本功。

7.2 把能力串成体系

回头看，Image 的能力也是分层的：底层是"把图显示出来"（四种来源），往上是"显示得好看"（objectFit），再往上是"显示得稳"（alt/onComplete/onError 兜底），最后是"显示得快"（三级缓存与列表性能），更深处还有"显示得省"（采样解码）。每一层对应一类真实业务：

为了把全文知识收成一张"地图"，便于日后速查，按"问题 → 解法 → 关键 API"三列汇总如下：

这张表几乎覆盖了图片开发的全部高频问题。把它贴在工位上，比每次临时搜文档高效得多。真正熟练的标志，不是记得每个参数，而是看到业务需求时，能立刻在表里找到对应的那一行。

• 图标、背景 → $r 资源，离线优先；
• 头像、封面 → Cover + 固定尺寸；
• 网络 UGC → alt 占位 + onError 兜底；
• 图集、信息流 → 缓存 + 懒加载。

把这几层吃透，图片相关的"白屏、变形、掉帧、费流量"四大顽疾基本都能对症下药。

后续可沿三条线深入：

1. 图片编辑：结合 @kit.ImageKit 把网络图解码成 PixelMap，做裁剪、旋转后再用 Image(pixelMap) 回显；
2. 自定义缓存策略：对特殊业务（如大图预览）研究磁盘配额与清理时机；
3. 列表极致优化：用 LazyForEach + cachedCount 调优滑动流畅度，配合 Profiler 看图片解码耗时。

7.3 避坑案例集：三个真实教训

理论讲完，用三个贴近实战的案例把前面知识点收口。这些场景你在项目里大概率会撞上。

案例一：首页 banner 用网络图，开屏就白屏。 某应用把首屏最大的一张 banner 走网络加载，结果用户进首页前两秒满屏白。根因是"首屏关键图不该依赖网络"。修正做法：banner 用 $r 资源做默认底图，Image 先显示资源图，网络图加载完成后再覆盖；或至少保证 alt 是一张品牌色占位，而不是空白。关键图永远要有"本地兜底"意识。

案例二：信息流下滑越来越卡，最终闪退。 排查发现列表里每张图都是原图（手机拍的 4000×3000），ForEach 一次性全量创建 Image，几十张图同时解码，内存直冲上限。修正做法：服务端按列表显示尺寸下发 300×300 缩略图；列表改 List + LazyForEach，不在屏的不创建；必要时给 Image 加 .syncLoad(false) 让解码异步不阻塞 UI 线程。三管齐下，滑动帧率从个位数回到满帧。

案例三：头像更新后用户还看到旧图。 产品改了头像，旧用户打开却还是老图。根因是 URL 没变，缓存命中了旧数据。修正做法：头像 URL 带版本号或时间戳（如 avatar.png?v=2），或更新后主动清理对应缓存。这正呼应了前文"强实时性图片绕过缓存"的技巧——缓存是双刃剑，复用它的同时也要知道何时绕开它。

这三个案例的共同点是：问题都不在某一行代码写错，而在"有没有把图片当作一等公民去管理"。白屏源于来源选错，卡顿源于尺寸与回收失配，旧图源于缓存策略没想清。把本文的"来源—缩放—兜底—缓存—回收—采样"六环都照顾到，这类问题在写代码时就能被提前消灭。

图片是界面里最"重"的元素，把它管好了，应用的体感就轻了一大半。