Image 加载图片,最容易被忽略的其实是显示模式
很多人用 Image,把图片地址一填,图是显示出来了,可一看:人脸被拉变形了、商品图被裁掉一半、头像挤成了椭圆。然后开始怀疑是不是图片本身有问题,其实图片好好的,问题出在你没设显示模式。
在华为仓颉编程语言开发华为鸿蒙系统应用时,Image 组件有个特别关键、又特别容易被新手跳过的属性,叫 `objectFit`,它决定图片在容器里到底怎么摆放。这篇就把显示模式讲透,顺带说说占位图和加载事件这两个同样实用的细节。
先搞清楚问题:图片和容器的尺寸不一样
为什么图片会变形或被裁?因为图片有它自己的原始尺寸和比例,而你给 Image 设的宽高往往是另一个比例。两个比例对不上,框架就得决定:是拉伸填满,还是保持比例留白,还是裁掉多余部分?
import kit.ArkUI.* Image("https://example.com/photo.jpg") .width(200) .height(200)
像这样把一张长方形图片塞进 200×200 的正方形容器,如果不告诉框架该怎么处理这个比例差,它就按默认方式来,结果往往不是你想要的。而控制这个行为的,就是 `objectFit`。
核心属性:objectFit 决定图片怎么填充
`objectFit` 接收一个 `ImageFit` 枚举值,告诉框架图片该如何适配容器。它的默认值是 `Cover`。
Image("photo.jpg") .width(200) .height(200) .objectFit(ImageFit.Contain)
记住最常用的三个:`Cover` 保持比例铺满容器,超出部分裁掉,适合头像、封面这种「宁可裁也要铺满」的场景;`Contain` 保持比例完整显示,容器空余处留白,适合商品图这种「必须看全」的场景;`Fill` 直接拉伸填满,不管比例,所以最容易让图变形。选错模式,就是变形和被裁的根源。

几种模式怎么选:场景对号入座
光知道枚举值还不够,关键是什么场景用哪个。这里给你一个对照思路。
Cover→ 头像、Banner、卡片封面(要铺满,可裁切) Contain→ 商品图、海报、图标(要完整,可留白) Fill→ 几乎不用(会变形,除非你确定要拉伸) ScaleDown → 小图不放大、大图按比例缩小
绝大多数场景,你在 `Cover` 和 `Contain` 之间选就够了:怕留白、要视觉冲击就用 `Cover`,怕裁掉关键内容就用 `Contain`。养成「设宽高就顺手设 objectFit」的习惯,变形问题基本就绝迹了。

别忘了占位:alt 让加载过程不尴尬
网络图片不是瞬间就到的,加载那一两秒,如果什么都不显示,页面会闪一下空白,体验很差。`alt` 属性就是用来填这个空当的。
Image("https://example.com/photo.jpg") .alt(@r(app.media.placeholder)) .objectFit(ImageFit.Cover)
`alt` 设置的是占位图,在真正的图片加载完成之前,先显示这张本地图。这样用户看到的是一张占位图平滑过渡到真图,而不是空白突然变图。列表里大量加载网络图时,加不加 `alt`,观感差距非常明显。
加载状态要管:onComplete 和 onError
图片加载有成功也有失败,把这两个状态接住,App 才显得稳。Image 提供了对应的事件。
Image("https://example.com/photo.jpg") .onComplete({ evt => /* 加载成功 */ }) .onError({ evt => /* 加载失败,可显示兜底图 */ })
`onComplete` 在图片加载成功后触发,`onError` 在加载失败时触发。最实用的用法是在 `onError` 里做兜底:网络图挂了,就换上一张默认图,而不是给用户留个破裂的图标。把失败情况也考虑到,是专业和业余的分水岭。

显示模式用对,图片才真正「显示对了」
回头看,用 Image 显示图片,真正的功夫不在「让图出现」,而在这几个容易被忽略的细节:`objectFit` 决定它摆得对不对,`alt` 让加载过程不尴尬,`onComplete` 和 `onError` 把成功失败都兜住。

下次写 Image,填完地址别急着划走,顺手把 `objectFit` 设一下。就这一个小习惯,能帮你避开八成的图片显示问题。把细节抠到位,页面才经得起看。