Image是鸿蒙ArkUI最核心的图片渲染组件，几乎所有App都会用到图标、banner、用户头像、商品图、占位图等场景。很多开发者只会简单写 Image().width().height()，但遇到图片拉伸、裁切异常、网络图加载失败、适配错位、圆角黑边、清晰度失真等问题时无从下手。
本文从零完整梳理 Image 组件：5种资源加载方式 + 6种缩放裁剪模式 + 进阶属性 + 网络权限配置 + 实战场景 + 高频坑点，所有代码均可直接复制运行，适合收藏当做开发手册。
一、Image 组件基础概述
Image 组件用于渲染各类图片资源，默认尺寸为 320vp × 240vp，不手动设置宽高极易出现布局错乱。
支持渲染资源类型：本地媒体资源、rawfile静态资源、网络图片、本地路径图片、Base64图片，覆盖移动端所有图片业务场景。
核心核心能力：通过 objectFit 实现缩放/裁剪、borderRadius 实现圆形/圆角图、alt 占位、加载监听、图片模糊、颜色滤镜等。
二、5种图片资源加载方式（全覆盖示例）
鸿蒙Image资源加载分5类，不同场景严格区分使用，混用会出现打包失效、读取失败、热更新无效等问题。
1. 常规本地媒体资源（$r）------ 图标、固定配图首选
资源路径：resources/base/media/，会被编译压缩，支持多设备适配、多语言适配，适合图标、logo、常驻配图。
// 加载media目录下的图片
Image($r('app.media.ic_logo'))
.width(120)
.height(120)2. rawfile资源（$rawfile）------ 不压缩原图、动态素材首选
资源路径：resources/rawfile/，不编译、不压缩、保留原图质量，适合启动页、海报、高清大图、动态配置素材。
// 加载rawfile原图资源
Image($rawfile('banner_bg.png'))
.width('100%')
.height(180)3. 网络图片资源 ------ 动态banner、用户头像、商品图
直接传入网络URL，必须配置网络权限，否则加载空白。
权限配置（module.json5）：
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]网络图片加载示例（带占位图）：
Image('https://picsum.photos/600/300')
.width('100%')
.height(180)
// 加载失败/加载中占位图
.alt($r('app.media.img_default'))4. 本地绝对路径图片 ------ 相册、下载图片渲染
用于渲染应用沙盒、手机相册、下载目录的本地图片文件，适配用户自定义图片场景。
// 示例：沙盒路径图片（实际业务需替换真实路径）
Image('/data/storage/el2/base/haps/entry/files/test.jpg')
.width(200)
.height(200)5. Base64图片渲染 ------ 二维码、临时缩略图
适合接口返回Base64格式图片（二维码、头像缩略图），无需本地存文件，直接渲染。
// 简化Base64示例（业务直接替换完整base64字符串）
Image('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==')
.width(100)
.height(100)三、核心重点：6种缩放裁剪模式 objectFit 全解析
objectFit 是Image组件最容易出Bug、面试高频、业务最常用的属性，决定图片在设定宽高容器内的缩放、拉伸、裁剪规则。
测试统一条件：容器 200vp×200vp，原图比例 3:1（宽图），方便直观对比差异。
1. ImageFit.Cover（默认）------ 居中裁剪、铺满容器、无拉伸
业务最常用：头像、banner、封面图。等比放大图片，铺满整个容器，超出部分居中裁剪，无拉伸、无留白。
Image($rawfile('banner'))
.width(200)
.height(200)
.objectFit(ImageFit.Cover)2. ImageFit.Contain ------ 完整显示、等比缩放、可能留白
适合图标、Logo、需要完整展示内容的图片。等比缩小/放大图片，让图片完整显示在容器内，不裁剪、不拉伸，不足区域留白。
Image($r('app.media.ic_logo'))
.width(200)
.height(200)
.objectFit(ImageFit.Contain)3. ImageFit.Fill ------ 完全拉伸铺满（慎用！）
直接拉伸图片宽高适配容器，会破坏图片比例、导致变形失真，仅纯色背景图可使用，禁止用于头像、商品图、图标。
Image($rawfile('bg'))
.width(200)
.height(200)
.objectFit(ImageFit.Fill)4. ImageFit.None ------ 原图尺寸、不缩放、居中展示
保持图片原始像素尺寸，不缩放，在容器内居中展示，超出容器部分直接裁剪，小于容器则居中留白。
Image($r('app.media.ic_logo'))
.width(200)
.height(200)
.objectFit(ImageFit.None)5. ImageFit.ScaleDown ------ 大图缩小、小图不变
图片尺寸大于容器则等比缩小（同Contain），小于容器则保持原图大小（同None），保证图片不放大失真，适合高清缩略图展示。
Image($rawfile('hd_img'))
.width(200)
.height(200)
.objectFit(ImageFit.ScaleDown)6. ImageFit.TOP / BOTTOM / LEFT / RIGHT ------ 定向裁剪
默认Cover是居中裁剪，如需顶部裁剪（banner常用）、底部裁剪，可使用定向模式。
示例：Banner图顶部裁剪（保留图片顶部内容，适配海报场景）
Image($rawfile('banner'))
.width('100%')
.height(180)
.objectFit(ImageFit.Top)四、高频实战场景：圆角、圆形头像、模糊、占位图
1. 圆形头像（终极正确写法，无黑边、无留白）
关键点：Cover裁剪 + 等宽高 + 50%圆角，是鸿蒙圆形头像标准方案，彻底解决裁剪不全、黑边问题。
// 完美圆形头像
Image('https://picsum.photos/200/200')
.width(100)
.height(100)
.borderRadius('50%')
.objectFit(ImageFit.Cover)
.alt($r('app.media.avatar_default'))2. 圆角图片（卡片配图通用）
Image($rawfile('goods'))
.width('100%')
.height(160)
.borderRadius(12)
.objectFit(ImageFit.Cover)3. 图片模糊效果（毛玻璃、背景虚化）
Image($rawfile('bg'))
.width('100%')
.height(200)
.objectFit(ImageFit.Cover)
.blur(8) // 模糊度数，数值越大越模糊4. 颜色滤镜（图片变色、主题适配）
// 图标全局变色适配主题
Image($r('app.media.ic_tab'))
.width(24)
.height(24)
.color('#007AFF')五、图片加载监听、进度、失败重试（工程必备）
生产项目必须监听图片状态，处理加载成功、失败、进度，适配重试、隐藏加载动画、错误兜底场景。
@Entry
@Component
struct ImageLoadDemo {
build() {
Column() {
Image('https://picsum.photos/600/300')
.width('100%')
.height(180)
.objectFit(ImageFit.Cover)
// 加载进度回调
.onProgress((loaded, total) => {
console.log('图片加载进度：', loaded, '/', total);
})
// 加载成功
.onSuccess((event) => {
console.log('图片加载成功，宽高：', event.width, event.height);
})
// 加载失败兜底
.onError(() => {
console.log('图片加载失败');
})
}
}
}六、坑点
坑点1：网络图片空白不显示
原因：未配置 ohos.permission.INTERNET 网络权限；URL含特殊字符、HTTPS证书异常；网络未授权。
解决：配置权限、校验URL有效性、添加占位图兜底。
坑点2：圆角图片出现黑边/留白
原因：使用Contain模式图片留白，底色透明/黑色；宽高不相等导致圆形裁剪变形。
解决：头像用Cover裁剪，保证宽高一致；卡片图统一Cover铺满。
坑点3：图片拉伸变形严重
原因：默认Cover被改成Fill，或容器比例与图片比例严重不匹配。
解决：业务图片统一Cover，背景图按需使用Fill。
坑点4：rawfile图片改名后加载失败
原因：区分大小写、后缀名写错、路径层级错误。
解决：严格匹配文件名大小写，统一小写命名规范。
坑点5：大图模糊失真
原因：media资源被编译压缩，高清图放media目录。
解决：高清大图、海报图统一放入rawfile目录。