当前位置：首页 > news >正文

HarmonyOS开发：Image使用详解

news 来源：原创 2025/5/31 14:57:31

前言

在当今数字化时代，用户界面的视觉效果对于提升用户体验起着至关重要的作用，而图片作为视觉元素的核心组成部分，在各类应用中扮演着不可或缺的角色。无论是用于展示产品的精美图片、传递信息的图标，还是营造氛围的背景图，恰当且高效的图片使用都能极大地增强应用的吸引力和易用性。而HarmonyOS作为面向未来全场景智能设备的操作系统，为开发者提供了强大的图像处理和展示能力，其中Image组件便是实现丰富视觉效果的关键工具之一。对于HarmonyOS开发者而言，深入理解并掌握Image组件的使用方法，不仅可以帮助我们构建出更具吸引力的用户界面，还能在性能优化和资源管理方面发挥重要作用。通过合理配置Image组件的属性和方法，我们能够实现图片的高效加载、流畅展示以及与其他UI组件的无缝集成，无论是开发面向移动设备的应用，还是针对智能穿戴设备、智能家居设备等不同场景的应用，Image组件都能为我们提供强大的支持。那么本文就来深入探讨HarmonyOS中Image组件的使用方法，从基础属性配置到高级功能实现，从静态图片展示到动态效果处理，全方位剖析Image组件的特性和应用场景。

Image组件基础

1、Image组件概述

在HarmonyOS的UI开发中，Image为图片组件，它是用于展示图片资源的基本组件，常用于在应用中显示图片。Image支持加载PixelMap、ResourceStr和DrawableDescriptor类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式，并且提供了丰富的属性和方法来控制图片的显示效果、加载方式以及与其他UI元素的交互。通过合理使用Image组件，开发者可以轻松地在应用中添加各种图片资源，提升应用的视觉表现力。

2、需要权限

使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考声明权限。

3、Image接口

Image(src: PixelMap | ResourceStr | DrawableDescriptor)

通过图片数据源获取图片，用于后续渲染展示。

Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。
Image组件默认按照居中裁剪，例如组件宽高设置相同，原图长宽不等，此时按照中间区域进行裁剪。
Image加载成功且组件不设置宽高时，其显示大小自适应父组件。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

4、Image组件的基本属性

属性的详细使用指导请参考添加属性。（注意：Image组件不支持设置通用属性foregroundColor，可以通过Image组件的fillColor属性设置填充颜色。）除支持通用属性外，还支持以下属性（这里只介绍日常开发中Image组件常用的属性）：

(1) src

描述：指定图片资源的路径。可以是本地资源路径，也可以是网络资源的URL。

类型：Resource或string

(2) width 和 height

描述：设置图片的显示宽度和高度。支持像素（px）、百分比（%）等单位。

类型：Length

示例：

Image($r('app.media.friend_bg')).width('100%').height(200)

(3) objectFit

objectFit(value: ImageFit)

设置图片的填充效果。

描述：控制图片如何适应其容器。常见的值有contain、cover、fill、none、scale-down。

类型：ObjectFit

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

示例：

Image($r('app.media.friend_bg')).width('100%').height(200).objectFit(ImageFit.Fill)

(4) alt

alt(value: string | Resource | PixelMap)

设置图片加载时显示的占位图。

占位图支持使用objectFit设置填充效果，与图片的填充效果一致。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

描述：为图片提供替代文本，当图片无法显示时，替代文本将被展示。

类型：string

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

示例：

Image(this.bloggerInfo?.icon ?? $r('app.media.ic_user_portrait')).width(58).height(58).borderRadius('50%').clip(true) .border({width:3, color: Color.Green}).alt(this.alt)

(5) imageMatrix（15+）

imageMatrix(matrix: ImageMatrix)

设置图片的变换矩阵。通过ImageMatrix对象使用平移、旋转、缩放等函数，实现宫格缩略图的最佳呈现。svg类型图源不支持该属性。

设置resizable、objectRepeat属性时，该属性设置不生效。该属性只针对图源做处理，不会触发Image组件的回调事件。

该属性与objectFit属性强关联，仅在objectFit属性设置为ImageFit.MATRIX时生效。

元服务API：从API version 15开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

(6) sourceSize

sourceSize(value: { width: number; height: number })

设置图片解码尺寸。仅在目标尺寸小于图源尺寸时生效。svg类型图源和PixelMap资源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

(7) interpolation

interpolation(value: ImageInterpolation)

设置图片的插值效果，即缓解图片在缩放时的锯齿问题。svg类型图源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

5、Image组件的基本方法（事件）

除支持通用事件（比如点击事件、触摸事件、挂载卸载事件、拖拽事件、按键事件、焦点事件、鼠标事件、悬浮事件、无障碍悬浮事件、组件区域变化事件、组件尺寸变化事件、组件可见区域变化事件、组件快捷键事件、自定义事件分发、自定义事件拦截、焦点轴事件、轴事件）外，还支持以下事件：

（1）onComplete

onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number }) => void)

图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

（2）onFinish

onFinish(event: () => void)

当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。

仅支持svg格式的图片。当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

（3）onError（9+）

onError(callback: ImageErrorCallback)

图片加载异常时触发该回调。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

Image组件的高级功能

上面介绍的是常用的Image组件的基础功能，接下来介绍它的高级功能（这里也是介绍几个常用的功能）。

1、ImageErrorCallback9+

type ImageErrorCallback = (error: ImageError) => void

图片加载异常时触发此回调。

当组件的参数类型为AnimatedDrawableDescriptor（Image组件播放PixelMap数组时传入AnimatedDrawableDescriptor对象。继承自DrawableDescriptor。）时该事件不触发。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

2、ImageError（9+）

图片加载异常时触发回调的返回对象。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

3、图片的动态加载

在实际开发中，我们常常需要根据用户的操作动态加载图片。例如，在一个图片浏览应用中，用户点击某个缩略图时，我们需要加载并展示对应的高清图片。Image组件提供了灵活的动态加载机制，支持通过代码动态设置src属性来加载图片。加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。使用HTTP工具包发送网络请求，接着将返回的数据解码为Image组件中的PixelMap，图片开发可参考图片处理。使用网络图片时，需要申请权限ohos.permission.INTERNET。具体的示例代码如下所示：

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';@Entry
@Component
struct ImageExample2 {@State pixelMapImg: PixelMap | undefined = undefined;aboutToAppear() {this.requestImageUrl('https://www.example.com/xxx.png'); // 请填写一个具体的网络图片地址}requestImageUrl(url: string) {http.createHttp().request(url, (error: BusinessError, data: http.HttpResponse)=> {if (error) {console.error(`request image failed: url: ${url}, code: ${error.code}, message: ${error.message}`);} else {let imgData: ArrayBuffer = data.result as ArrayBuffer;console.info(`request image success, size: ${imgData.byteLength}`);let imgSource: image.ImageSource = image.createImageSource(imgData);class sizeTmp {height: number = 100;width: number = 100;}let options: Record<string, number | boolean | sizeTmp> = {'alphaType': 0,'editable': false,'pixelFormat': 3,'scaleMode': 1,'size': { height: 100, width: 100 }}imgSource.createPixelMap(options).then((pixelMap: PixelMap) => {console.error('image createPixelMap success');this.pixelMapImg = pixelMap;})imgSource.release()}})}build() {Column() {Image(this.pixelMapImg).alt($r('app.media.img')).objectFit(ImageFit.None).width('100%').height('100%')}}
}

4、图片的懒加载

对于包含大量图片的应用，如图片列表或无限滚动的页面，懒加载是一种常用的优化技术。通过懒加载，只有当图片进入可视区域时才开始加载，从而减少初始加载时间和内存占用。虽然HarmonyOS的Image组件本身没有直接提供懒加载功能，但我们可以结合页面滚动事件和图片位置信息来实现懒加载。

5、图片的动画效果

为了提升用户体验，我们可以在图片展示时添加一些动画效果。例如，当图片加载完成时，可以添加一个淡入效果，或者在图片切换时添加一个平滑的过渡效果。Image组件支持与其他动画组件结合使用，实现丰富的动画效果。

6、图片的适配与响应式设计

在多设备适配的场景下，我们需要确保图片在不同屏幕尺寸和分辨率下都能保持良好的显示效果。Image组件支持响应式设计，可以通过设置width和height属性的百分比值，或者使用媒体查询来实现适配。

Image组件的最佳实践

1、图片资源优化

为了提升应用的性能，我们需要对图片资源进行优化。包括压缩图片大小、选择合适的图片格式、使用图片懒加载等。通过这些优化措施，可以减少图片加载时间，降低内存占用，提升应用的响应速度。

2、错误处理与容错机制

在图片加载过程中，可能会出现各种错误，如网络问题、图片资源不存在等。我们需要为Image组件添加错误处理机制，确保在图片加载失败时，能够提供友好的提示或备用图片。

3、性能监控与分析

在应用开发过程中，我们需要对图片加载性能进行监控和分析。通过监控图片加载时间、内存占用等指标，可以及时发现性能瓶颈，优化应用性能。

案例分析

1、加载基本类型图片

假设加载png、gif、svg和jpg等基本类型的图片。具体示例代码如下：

@Entry
@Component
struct ImageExample1 {build() {Column() {Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {Row() {// 加载png格式图片Image($r('app.media.ic_camera_master_ai_leaf')).width(110).height(110).margin(15).overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })// 加载gif格式图片Image($r('app.media.loading')).width(110).height(110).margin(15).overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })}Row() {// 加载svg格式图片Image($r('app.media.ic_camera_master_ai_clouded')).width(110).height(110).margin(15).overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })// 加载jpg格式图片Image($r('app.media.ic_public_favor_filled')).width(110).height(110).margin(15).overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })}}}.height(320).width(360).padding({ right: 10, top: 10 })}
}

2、为图片添加事件

假设为图片添加onClick和onFinish事件。具体示例代码如下：

@Entry
@Component
struct ImageExample3 {private imageOne: Resource = $r('app.media.earth');private imageTwo: Resource = $r('app.media.star');private imageThree: Resource = $r('app.media.moveStar');@State src: Resource = this.imageOne;@State src2: Resource = this.imageThree;build(){Column(){// 为图片添加点击事件，点击完成后加载特定图片Image(this.src).width(100).height(100).onClick(() => {this.src = this.imageTwo;})// 当加载图片为SVG格式时Image(this.src2).width(100).height(100).onFinish(() => {// SVG动效播放完成时加载另一张图片this.src2 = this.imageOne;})}.width('100%').height('100%')}
}

3、为图像设置填充效果

该示例通过objectFit为图像设置填充效果。具体示例代码如下：

@Entry
@Component
struct ImageExample{build() {Column() {Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {Row() {// 加载png格式图片Image($r('app.media.sky')).width(110).height(110).margin(15).overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }).border({ width: 2, color: Color.Pink }).objectFit(ImageFit.TOP_START)// 加载gif格式图片Image($r('app.media.loading')).width(110).height(110).margin(15).overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }).border({ width: 2, color: Color.Pink }).objectFit(ImageFit.BOTTOM_START)}Row() {// 加载svg格式图片Image($r('app.media.svg')).width(110).height(110).margin(15).overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }).border({ width: 2, color: Color.Pink }).objectFit(ImageFit.TOP_END)// 加载jpg格式图片Image($r('app.media.jpg')).width(110).height(110).margin(15).overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }).border({ width: 2, color: Color.Pink }).objectFit(ImageFit.CENTER)}}}.height(320).width(360).padding({ right: 10, top: 10 })}
}

4、为图片添加变换效果

该示例通过imageMatrix和objectFit属性，为图片添加旋转和平移的效果。具体示例代码如下：

import { matrix4 } from '@kit.ArkUI';@Entry
@Component
struct Test {private matrix1 = matrix4.identity().translate({ x: -400, y: -750 }).scale({ x: 0.5, y: 0.5 }).rotate({x: 2,y: 0.5,z: 3,centerX: 10,centerY: 10,angle: -10})build() {Row() {Column({ space: 50 }) {Column({ space: 5 }) {Image($r("app.media.example")).border({ width:2, color: Color.Black }).objectFit(ImageFit.Contain).width(150).height(150)Text("图片无变换").fontSize('25px')}Column({ space: 5 }) {Image($r("app.media.example")).border({ width:2, color: Color.Black }).objectFit(ImageFit.None).translate({ x: 10, y: 10 }).scale({ x: 0.5, y: 0.5 }).width(100).height(100)Text("Image直接变换，默认显示图源左上角。").fontSize('25px')}Column({ space: 5 }) {Image($r("app.media.example")).objectFit(ImageFit.MATRIX).imageMatrix(this.matrix1).border({ width:2, color: Color.Black }).width(150).height(150)Text("通过imageMatrix变换，调整图源位置，实现最佳呈现。").fontSize('25px')}}.width('100%')}}
}

结束语

通过本文的详细介绍，我们全面了解了HarmonyOS中Image组件的使用方法，从基础属性配置到高级功能实现，从静态图片展示到动态效果处理，全方位剖析了Image组件的特性和应用场景。Image组件作为HarmonyOS UI开发中的重要组成部分，为开发者提供了强大的图片处理和展示能力，帮助我们构建出更具吸引力的用户界面。在实际开发中，合理使用Image组件不仅可以提升应用的视觉表现力，还能在性能优化和资源管理方面发挥重要作用。通过动态加载、懒加载、动画效果、适配与响应式设计等技术手段，我们可以实现图片的高效加载、流畅展示以及与其他UI组件的无缝集成。同时，结合图片资源优化、错误处理与容错机制、性能监控与分析等最佳实践，我们能够进一步提升应用的质量和用户体验。希望本文的介绍和示例代码能够帮助大家在HarmonyOS开发中更好地使用Image组件，无论是开发面向移动设备的应用，还是针对智能穿戴设备、智能家居设备等不同场景的应用，都能轻松应对。