企业官网建设流程全解析

做鸿蒙应用开发，不管你做的是什么形态的应用——手机、平板还是智能座舱、大屏，界面上几乎都离不开图片。商品列表、用户头像、轮播 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 到 1，0 完全透明，1 完全不透明。这个属性在做图片渐变显示、点击态高亮时会用到。基础篇只要知道这个属性存在、能作用于整张图片区域就可以了。

.interpolation()是插值属性，作用是控制图片缩放时的平滑度，默认是低插值模式，性能好但图片缩小后可能出现边缘锯齿。如果真的对图片缩小的清晰度有要求，可以设置成.interpolation(ImageInterpolation.High)，代价是渲染性能会差一点。一般场景不建议全局开 High，图片一多列表会明显变卡。

2.4 组合属性速查表

这个表格看起来只是把属性罗列了一遍，但实际开发里我每次调样式都要反复对照这几个属性。团队协作时，不管谁接手 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 里直接放 Image，Column 高度没有撑开，图片就会塌陷。排查方法是在 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 的进阶用法，包括图片懒加载、长图预览、手势缩放等实际项目高频场景的处理方案。