做鸿蒙应用开发不管你做的是什么形态的应用——手机、平板还是智能座舱、大屏界面上几乎都离不开图片。商品列表、用户头像、轮播 banner、富文本插图这些场景背后用到的基础组件其实都是同一个Image。这篇文章要聊的就是 ArkUI 里最常用也最基础的图片展示组件从组件定位、资源加载方式讲到核心属性的细节差异最后带大家从零搭一个能直接练手的图片展示页面。这是 UI 基础篇的第十六节定位是基础篇所以不会碰自定义绘制或者底层渲染那套东西但会把日常开发里真正能用到的点讲透尤其是那些看起来顺手、跑起来却容易出问题的细节。1. Image 组件的前置认知先搞懂它能干什么1.1 官方定位与适用场景Image 是 ArkUI 提供的基础图片组件用来在页面上渲染一张图片支持本地资源、网络资源和内存像素图三种输入来源也支持基础的缩放、裁剪、圆角、透明度等修饰效果。它的地位相当于 Web 里的 img 标签或者 Flutter 里的 Image widget凡是界面上要“显示一张图”的需求第一反应都应该落到它身上。我见过不少刚接触鸿蒙开发的同学一上来就想着用 Canvas 去画图或者自定义组件去搞图片展示其实大部分时候都没必要。单张图片展示、头像裁剪、卡片配图、轮播图、背景图、图片按钮这些基础场景 Image 组件原生就能覆盖而且性能和内存管理是系统帮我处理好的比自己写一个图片加载 View 要靠谱得多。适用场景可以大致分成四类静态配图详情页插图、引导页、logo基本都是本地图片直接展示。动态数据配图网络图片比如用户头像、商品缩略图、运营 banner需要从远端拉取。图片装饰按钮图标、列表 item 的缩略图对加载速度和缓存要求比较高。图片预览点击放大、双指缩放、左右滑动切换通常要配合手势系统一起做。基础篇里我们先把前两类做扎实第三类和第四类是进阶篇的内容后面会单独展开。1.2 图片资源的三种加载方式Image 组件加载图片首先要确定图片从哪里来。在 ArkUI 里面常见的有三种方式本地 media 资源、本地 rawfile 资源和网络图片地址。第一种是$r(app.media.xxx)这是使用频率最高的写法引用的图片放在src/main/resources/base/media目录下。系统会自动根据设备类型和资源配置做匹配比如横屏竖屏、深浅色模式如果同一张图有不同版本直接按资源限定词命中不用自己在代码里判断。第二种是$rawfile(xxx.png)引用的是src/main/resources/rawfile目录下的文件。这个目录的特点是不会被编译处理适合放一些不希望系统改动资源配置的原始文件比如模型文件、普通的 JSON 配置当然图片也能放。两者的区别可以这样理解media 是“让系统帮我管理的资源”rawfile 是“我自己原封不动使用的文件”。实际开发里如果只是普通图片展示优先用 media如果图片是某个功能包的一部分、需要和代码一起打包且不参与资源编译再用 rawfile。第三种是直接传网络地址字符串比如Image(https://example.com/a.png)。这种写法最直接但要注意几个前提。网络图片必须在前置配置里声明网络访问权限否则请求发不出去另外网络图片加载是异步的从用户点击页面到图片真正渲染出来中间有延迟所以一般要配合占位图使用展示效果才不会突兀。内存像素图的加载方式PixelMap在基础场景里相对少见一般是拍照、相册选择这类场景拿到图片数据之后直接塞给 Image 渲染用暂时可以先放一放。注意本地图片的路径不能以/开头直接写绝对路径也不能用file://的方式去引用 media 目录这些都是没配好资源引用方式的典型报错。2. 核心属性拆解每个参数背后的效果逻辑2.1 src 和 alt图片来源与失败兜底src是 Image 组件的核心属性负责指定图片的来源前面讲的三种加载方式都是通过它来配置的。基础用法并不复杂但有一个容易被忽视的点src 的值在运行期是几套不同的类型体系写字符串、写$r、写$rawfile对应的处理逻辑不一样后续要做动态切换的时候就要考虑好到底用哪种类型。比如商品列表里要根据返回的商品 ID 拼接头像地址那 src 自然就是动态的网络字符串但如果要切换本地多套皮肤资源用$r这种方式管理会更规范资源路径由编译期兜底检查写错了 IDE 直接标红比字符串肉眼检查要稳得多。alt属性是图片加载占位符在图片没有加载完成或者加载失败时显示。这里有一个实战经验基础篇阶段可能觉得 alt 可填可不填但到了实际项目里尤其网络图多的页面alt 几乎是必填的。不设置 alt图片加载失败之后页面就是一块空白或者一个破碎的默认图icon体验很差设置 alt 之后至少能给用户一个稳定的视觉反馈。alt 不只是文字占位也可以直接放一张本地占位图。在电商项目的列表页里我习惯的做法是先加载一张低清灰底的本地占位图等网络图回来之后替换掉这样避免列表滚动时光秃秃的一片空白视觉上会连贯很多。2.2 objectFit图片缩放的六种模式怎么选objectFit应该是 Image 组件里最值得花时间理解的一个属性它决定了图片在容器里怎么缩放和裁切。基础用法是通过objectFit(ImageFit.Contain)这样的链式写法来设置。ArkUI 里的ImageFit枚举常用取值有六个Contain、Cover、Fill、ScaleDown、None、Zoom。第一次接触的时候光看名字不容易分清我用实际场景来解释。Contain是把整张图片按比例缩放到容器内完整显示四周可能会留白。适合的场景是那种“必须完整展示内容”的图片比如证件的正反面扫描图、商品主图内容比铺满更重要。Cover是把图片按比例缩放让短边也覆盖住容器超出的部分裁掉。这是最常用的模式头像、卡片背景图、banner 基本都是用它。它的问题也很直观裁掉的区域不可控默认居中裁切如果图片主体不在正中间很可能会被切掉。比如一张人物的全身照用 Cover 放在一个 1:1 的头像框里大概率只露出来胸口以上头部如果偏上或偏下还会被削掉一部分所以用 Cover 的时候对图片来源结构要有预判。Fill是不保持比例直接拉伸铺满容器图片可能会变形。适合对图片内容不再意的场景比如纯色渐变背景图、纹理贴图但用在人物或产品图上就会显得很别扭。ScaleDown的效果是图片比容器大的时候缩到容器内并保持比例比容器小的时候保持原图大小不完全撑满。适合那种图片可大不可小的场景。None是不做任何缩放原图大小直接渲染超过容器边界就裁掉。适合已经精确算好尺寸的设计稿图片不需要代码里再加工。Zoom是图片按比例缩放到完全覆盖容器跟 Cover 类似但它更像“缩放”而不是“裁切”在部分场景下会跟容器贴合得更紧密具体差异要实测分辨率变化时才能感觉出来。提示如果选择Cover模式做头像图片主体是人物面部时建议把图片来源裁剪成接近正方形的构图或者在原图层面就处理好位置否则代码层面很难精准控制裁切焦点。2.3 尺寸、圆角、透明度等常用修饰属性Image 组件的宽高设置和通用组件一致是通过.width()和.height()链式控制支持数值、百分比、vp、fp等单位。需要记住的是宽高给的是容器的尺寸不代表图片自身的尺寸。容器尺寸确定之后图片填进去的视觉结果由 objectFit 决定。还有一个属性是.borderRadius()设置圆角。这个属性虽然写在 Image 上但实现上是对绘制区域做裁剪所以设置圆角之后图片四个角会直接显示为圆弧不会出现“图片是方的但圆角露白”的情况。这一点跟 Web 里 img 加 border-radius 的行为很接近但和 Flutter 里需要 clipBehavior 配合的 Blur 效果还不完全一样写起来反而省事。.opacity()控制透明度取值从 0 到 10 完全透明1 完全不透明。这个属性在做图片渐变显示、点击态高亮时会用到。基础篇只要知道这个属性存在、能作用于整张图片区域就可以了。.interpolation()是插值属性作用是控制图片缩放时的平滑度默认是低插值模式性能好但图片缩小后可能出现边缘锯齿。如果真的对图片缩小的清晰度有要求可以设置成.interpolation(ImageInterpolation.High)代价是渲染性能会差一点。一般场景不建议全局开 High图片一多列表会明显变卡。2.4 组合属性速查表属性作用常用取值示例常见坑src图片来源$r(app.media.icon)、网络地址路径写错、类型不匹配alt加载占位加载中、$r(app.media.placeholder)不设置导致空白objectFit缩放裁切模式ImageFit.Cover、ImageFit.ContainCover 裁掉主体width / height容器尺寸100vp、100%忘记给宽高图片不显示borderRadius圆角8vp、16vp设置后视觉效果与内容有关opacity透明度0.5影响整体含内容interpolation缩放开平滑ImageInterpolation.High高插值影响性能这个表格看起来只是把属性罗列了一遍但实际开发里我每次调样式都要反复对照这几个属性。团队协作时不管谁接手 UI 层拿到这个速查表都能快速定位问题出在哪个维度——是图片来源、是容器尺寸、还是缩放规则出了问题。3. 实战环节从零搭建图片展示页面3.1 创建页面框架与引入图片资源这一节我们直接动手做一个可运行的页面。目标是做一个用户个人中心的头部卡片左侧是用户头像右侧是昵称和一句话简介底部是背景图整体用 Image 组件渲染。先创建一个标准页面在 DevEco Studio 里新建一个ProfilePage文件位置在entry/src/main/ets/pages/ProfilePage.ets基础的页面结构是 Column Row 排布顶部留状态栏安全边距。图片资源准备两张本地素材头像图放一张 200x200 的方图到resources/base/media/avatar.png背景图放一张 720x240 的横图到resources/base/media/bg.png引入方式写$r(app.media.avatar)和$r(app.media.bg)。这里要特别注意media 目录下的图片文件名不需要带后缀$r引用时也不写后缀这是一个新手常踩的坑。页面骨架代码如下Entry Component struct ProfilePage { State userName: string HUAWEI_USER State userDesc: string 路虽远行则将至 build() { Column() { Stack({ alignContent: Alignment.TopStart }) { // 背景图 Image($r(app.media.bg)) .width(100%) .height(160) .objectFit(ImageFit.Cover) Row({ space: 12 }) { // 头像 Image($r(app.media.avatar)) .width(56) .height(56) .borderRadius(28) .objectFit(ImageFit.Cover) Column({ space: 4 }) { Text(this.userName) .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor(Color.White) Text(this.userDesc) .fontSize(13) .fontColor(#CCFFFFFF) } .alignItems(HorizontalAlign.Start) } .margin({ left: 16, top: 32 }) } .width(100%) .height(160) .clip(true) // 下方内容区先用占位文本 Text(个人资料区) .margin({ top: 24 }) } .width(100%) .height(100%) .backgroundColor(#F1F3F5) } }这段代码里有一个关键点背景图的宽高需要在 Stack 容器里先确定不能只写width(100%)不写高度。在实际开发里很多图片“显示不出来”的案例排查到最后都是容器高度为零图片渲染不出来。3.2 用属性调整做出卡片效果上面代码跑起来应该能看到一张背景图和头像了但距离“能看的页面”还差一点质感我们逐步调。先把背景图的圆角和层级处理好。背景图目前是直角矩形放在页面顶部会显得生硬给主体区域加卡片化的样式背景图也加圆角并配合.clip(true)裁剪内部子元素不然背景图溢出圆角会看到直角。头像位置也想调整一下让它往左下角靠一点同时叠加一个细边框视觉上突出轮廓。给 Image 加.border({ width: 2, color: Color.White })这样头像在白色边框衬托下会更像真实的头像裁剪效果。调整之后的关键代码片段Stack({ alignContent: Alignment.TopStart }) { Image($r(app.media.bg)) .width(100%) .height(160) .borderRadius({ bottomLeft: 24, bottomRight: 24 }) .objectFit(ImageFit.Cover) .opacity(0.85) Row({ space: 12 }) { Image($r(app.media.avatar)) .width(64) .height(64) .borderRadius(32) .objectFit(ImageFit.Cover) .border({ width: 2, color: Color.White }) // text 区域省略 } .margin({ left: 16, top: 32 }) } .width(100%) .height(160) .clip(true)这里有个经验可以记一下圆角写在 Stack 上还是写在内部 Image 上效果完全不同。如果想让背景图变成圆角卡片要在 Image 本体上写borderRadius并且在父容器上加clip(true)保证子元素溢出被裁掉否则内部的头像仍可能超出圆角边界。还有.opacity(0.85)是我故意加的让背景图稍微降一点透明度文字层级更清晰。实际做卡片背景的时候除了调透明度也可以给背景图叠一层同色半透明遮罩效果会更好但那个要额外用 Stack 叠一个 Column 或 Row基础篇先不过度展开。3.3 网络图片加载与权限配置本地图片调试没问题之后下一步就是把头像换成网络图模拟真实业务场景。比如把头像地址换成一个远端 URL代码里写成Image(https://example.com/avatar.png) .width(64) .height(64) .borderRadius(32) .objectFit(ImageFit.Cover) .alt($r(app.media.placeholder))运行时需要做两件事。第一件事是配置网络权限在entry/src/main/module.json5文件里声明{ module: { requestPermissions: [ { name: ohos.permission.INTERNET } ] } }不配置这个权限网络图片请求会静默失败最常见的结果是图片区域一直显示占位图或者空白控制台会输出网络相关的错误日志。第二件事是确认图片来源域名是正常的 HTTPS 地址HTTP 明文地址在部分环境会被拦建议直接用 HTTPS。网络图片调试还有一个切身体会加载速度受网络环境影响很大代码层面表现就是图片出来有延迟。想要体验更好可以在 Image 外层包一个状态容器加载中转圈、加载完成后显示图片但这属于进阶写法基础篇里先用 alt 顶住后续再优化。4. 常见问题与排查技巧实录4.1 图片不显示的几类典型原因图片不显示是 Image 组件使用里最高频的问题我自己调试的时候都会把原因归类成几个方向逐个排查效率明显更高。第一类资源路径不对。$r(app.media.xxx)里的 xxx 写错、图片文件没放在 media 目录或者文件名带了下划线/空格都可能导致渲染失败。排查方法很简单看 IDE 的编译警告和运行日志如果报资源不存在那就是路径没对上。第二类容器尺寸为零。Image 本身有默认行为但如果父容器高度没有确定图片显示不出来或者只显示很小一块。比如 Column 里直接放 ImageColumn 高度没有撑开图片就会塌陷。排查方法是在 Image 上临时加一个背景色看区域是否存在。第三类网络权限没配好。前面提到的 INTERNET 权限漏配会导致网络图片全部失败。排查方法是在网络图片加载时看日志里是否有网络请求失败相关的报错。第四类objectFit 设置异常。某些极端情况下图片确实加载了但因为缩放模式导致视觉上看起来像没显示比如 Contain 模式配在一个和图片比例差距很大的容器里上下留白太多Cover 模式在很小容器里裁切到只剩纯色区域看起来像空白。这时快速切换几个 ImageFit 枚举立刻就能定位问题。4.2 图片发虚、模糊、裁切异常的处理图片显示出来但效果不对这类问题通常跟图片资源和缩放模式有关。发虚的根源一般是图片来源分辨率不够或者被拉伸了。容器宽度固定为 300vp但图片原始宽度只有 100px放大后肯定虚。解决办法是让设计切图时按设备宽度 2x 甚至 3x 尺寸提供代码层面能做的有限。裁切异常大部分是 objectFit 的锅。比如头像裁掉一半因为你用的是 Cover 模式但又没有控制图片主体位置。要解决要么让图片来源本身就符合容器比例要么把图片放进一个固定宽高的容器配合 ScaleDown 减少裁切量。有些项目直接选择不用 Cover 模式改用 Contain 加背景色垫底虽然四周会留白但内容完整度优先。另外一个容易被忽略的点是.interpolation()的插值模式。图片在手机上缩放比较多时低插值会让边缘出现锯齿看起来“发毛”。如果截图里能看出明显锯齿把插值改成 High 再看清晰度会有可感知的提升代价是列表滑动帧率会略降要自己权衡。4.3 性能与内存避坑经验图片组件用得越顺手越容易忽略性能问题。我这里分享几条实际项目里沉淀下来的经验。第一大图别直接硬塞。一个 4000x3000 的照片直接当全屏背景渲染内存占用会非常高。基础做法是通过图片工具压到合适分辨率再进工程页面上需要多大的尺寸就放多大的图不要指望 Image 自动降载。在鸿蒙应用里加载一张超大图导致内存抖动、甚至闪退的情况我是亲眼见过几次的。第二列表里的图片要注意复用。如果列表每个 Item 都有 Image不要在每个 Item build 里去执行高开销的图片处理逻辑。该用占位图的用占位图该上缓存的让框架去缓存避免重复请求网络资源。第三透明度和插值这类属性不要滥用。.opacity()和.interpolation(High)都会增加渲染负担尤其是页面里图片很多的时候能少用就少用。基础篇先把功能做出来后续性能优化时可以针对这些点做专项排查。提示在做图片性能排查时优先看资源体积和图片分辨率这两项几乎是所有图片卡顿问题的根因属性层面的优化只能起到辅助作用。5. 一些可以直接用的编码习惯最后聊几个我写 Image 组件时一直在用的编码习惯算是对基础篇内容的收尾。每张图片都要有确定的宽高。不管是本地图还是网络图都先想清楚这个 Image 要占多大的布局区域然后再决定 objectFit 的取法和 alt 的占位配置。这个习惯能帮你避免一大半图片不显示问题。图片资源统一管理。多人协作时把 media 目录的命名提前约定好比如缩略图统一加thumb_前缀头像统一用avatar_前缀配合$r的编译期检查代码可维护性会好很多。否则后期改一处图片全局搜字符串路径效率极低。网络图片一定要有降级方案。除了 alt 之外我习惯在请求层做一层判断如果网络图挂了就直接换成默认的本地图而不是等 Image 组件自己显示失败状态。这个思路在列表里尤其重要一个坏图会拖累整个列表的观感。Image 组件虽然基础但它是整个 UI 体系里使用面最广的组件之一。把它的资源加载、缩放规则、占位策略这几件事吃透后面写列表、写卡片、写个人中心都会顺手很多。基础篇的内容到这里就完整了下一篇我会继续展开 Image 的进阶用法包括图片懒加载、长图预览、手势缩放等实际项目高频场景的处理方案。