文章目录核心功能1 支持的本地图片格式2 核心API/属性使用完整代码示例关键代码1 布局容器适配2 本地图片加载核心语法3 overlay叠加文字标注4 尺寸与间距规范总结核心功能本示例聚焦Image组件本地静态/动态图片加载的核心基础能力覆盖HarmonyOS支持的主流图片格式同时结合布局组件实现多图片排版通过overlay属性实现图片文字标注是Image组件最常用的基础开发场景。1 支持的本地图片格式Image组件原生支持HarmonyOS本地资源中的主流图片格式本示例重点演示3种高频使用格式PNG静态位图支持透明通道适用于图标、按钮、静态配图等场景GIF动态位图支持简单动画效果适用于加载动画、状态动效等场景SVG矢量图支持无损缩放适配不同尺寸的设备屏幕适用于多端兼容的图标、插画等场景。2 核心API/属性使用本示例使用的Image组件核心属性均为HarmonyOS官方基础属性贴合实际开发高频使用场景具体说明如下属性名类型功能说明示例取值width/heightnumber设置图片宽高单位为vp虚拟像素适配不同屏幕密度110/110marginnumber/EdgeInsets设置图片外间距实现图片之间的间距隔离15 / { left:15, top:15 }overlay(content: stringCustomNode, options?: OverlayOptions) Image图片叠加层支持文字/自定义组件实现图片标注、水印等效果资源路径$r()Resource加载本地media目录下的图片资源格式为$r(app.media.资源文件名)$r(‘app.media.startIcon’)完整代码示例Entry Component struct ImageExample1 { build() { Column() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { Row() { // 加载png格式图片 // $r(app.media.ic_camera_master_ai_leaf)需要替换为开发者所需的图像资源文件。 Image($r(app.media.startIcon)) .width(110).height(110).margin(15) .overlay(png, { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) // 加载gif格式图片 // $r(app.media.loading)需要替换为开发者所需的图像资源文件。 Image($r(app.media.gif)) .width(110).height(110).margin(15) .overlay(gif, { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } Row() { // 加载svg格式图片 // $r(app.media.ic_camera_master_ai_clouded)需要替换为开发者所需的图像资源文件。 Image($r(app.media.start)) .width(110).height(110).margin(15) .overlay(svg, { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } } }.height(320).width(360).padding({ right: 10, top: 10 }) } }运行效果如图关键代码1 布局容器适配示例中使用ColumnFlexRow组合布局实现多图片的有序排列最外层Column设置固定宽高360vp×320vp和内间距限定图片展示区域中间层Flex设置纵向排列FlexDirection.Column子元素左对齐ItemAlign.Start保证两行图片左对齐展示内层Row实现同一行内的图片横向排列适配多图同行的展示需求。2 本地图片加载核心语法加载HarmonyOS本地media目录下的图片核心语法为Image($r(app.media.资源文件名))该方式为官方推荐的本地资源加载方式具备资源管理统一、适配多语言/多主题、加载性能优的特点。3 overlay叠加文字标注overlay属性是Image组件实现图片标注的高效方式本示例中核心配置第一个参数为叠加的文字内容如png直接传入字符串即可实现简单文字标注第二个参数为配置项align: Alignment.Bottom设置文字在图片底部对齐offset: { x: 0, y: 20 }设置文字在垂直方向向下偏移20vp避免文字与图片边缘重叠。4 尺寸与间距规范示例中为所有图片设置统一的width(110).height(110)保证图片展示大小一致通过margin(15)设置图片外间距实现图片之间的隔离提升视觉效果符合移动端UI设计的间距规范。总结资源路径规范本地图片必须放在src/main/resources/base/media目录下使用$r(app.media.xxx)加载不可使用相对路径/绝对路径直接加载GIF动效支持Image组件原生支持GIF动效无需额外配置放入media目录后直接加载即可自动播放暂不支持手动控制播放/暂停SVG无损缩放SVG图片设置任意width/height均不会模糊建议在需要适配多尺寸屏幕的场景优先使用SVG格式属性链式调用Image组件的所有属性均支持链式调用如.width(110).height(110).margin(15)代码简洁且符合ArkTS开发规范overlay偏移配置offset的x/y值可根据实际需求调整正数为向右/向下偏移负数为向左/向上偏移避免文字与图片内容重叠。图片占位图添加.alt($r(app.media.占位图资源名))属性实现图片加载失败时的占位图展示图片拉伸模式添加.objectFit(ImageFit.Cover)属性控制图片在固定宽高中的拉伸/裁剪方式常用值有Cover等比裁剪、Contain等比缩放、Fill填充图片圆角添加.borderRadius(10)属性实现图片圆角效果支持圆形图片borderRadius: 50%自定义overlay将overlay的第一个参数替换为自定义组件如overlay(() Text(图片标注).fontSize(12).fontColor(Color.White), { ... })实现文字样式自定义图片加载回调添加.onComplete(() {})和.onError(() {})属性实现图片加载成功/失败的回调处理便于做加载状态提示。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力