Image

Image为图片组件，常用于在应用中显示图片。Image支持加载PixelMap、ResourceStr和DrawableDescriptor类型的数据源，支持png、jpg、bmp、svg和gif类型的图片格式。

说明：

该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

需要权限

使用网络图片时，需要申请权限ohos.permission.INTERNET。

子组件

无

接口

Image(src: PixelMap | ResourceStr | DrawableDescriptor)

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

Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。

参数：

参数名	参数类型	必填	参数描述
src	PixelMap | ResourceStr | DrawableDescriptor	是	图片的数据源，支持本地的图片和网络图片。 1. PixelMap格式为像素图，常用于图片编辑的场景。 2. ResourceStr包含Resource和string格式。 string格式可用于加载网络图片和本地的图片，常用于加载网络图片。当使用相对路径引用本地的图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。 - 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp];base64,[base64 data], 其中[base64 data]为Base64字符串数据。 - 支持file://路径前缀的字符串。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 Resource格式可以跨包/跨模块访问资源文件，是访问本地的图片的推荐方式。 3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。 说明： - ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。 - ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。 - ArkTS卡片上不支持 PixelMap类型。 - 加载本地的图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。

属性

属性的详细使用指导请参考添加属性。除支持通用属性外，还支持以下属性：

名称	参数类型	描述
alt	string | Resource	加载时显示的占位图，支持本地的图片（png、jpg、bmp、svg和gif类型），不支持网络图片。 默认值：null 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
objectFit	ImageFit	设置图片的填充效果。 默认值：ImageFit.Cover
objectRepeat	ImageRepeat	设置图片的重复样式。从中心点向两边重复，剩余空间不足放下一张图片时会截断。 默认值：ImageRepeat.NoRepeat 说明： svg类型图源不支持该属性。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
interpolation	ImageInterpolation	设置图片的插值效果，即缓解图片在缩放时的锯齿问题。 默认值：ImageInterpolation.None 说明： 图片缩小显示时，High级别的interpolation算法不适用，建议使用Medium / Low。 svg类型图源不支持该属性。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
renderMode	ImageRenderMode	设置图片的渲染模式为原色或黑白。 默认值：ImageRenderMode.Original 说明： svg类型图源不支持该属性。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
sourceSize	{ width: number, height: number }	设置图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。 单位：px 说明： 仅在目标尺寸小于图源尺寸时生效。 svg类型图源不支持该属性。 PixelMap资源不支持该属性。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
matchTextDirection	boolean	设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。 默认值：false 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
fitOriginalSize	boolean	图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。 默认值：false 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
fillColor	ResourceColor	设置填充颜色，设置后填充颜色会覆盖在图片上。 说明： 仅对svg图源生效，设置后会替换svg图片的填充颜色。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
autoResize	boolean	设置图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会降采样解码到200x200的尺寸，大幅度节省图片占用的内存。 说明： 降采样解码时图片的部分信息丢失，因此可能会导致图片质量的下降（如：出现锯齿），这时可以选择把autoResize设为false，按原图尺寸解码，提升显示效果。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
syncLoad	boolean	设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。 默认值：false 说明： 建议加载尺寸较小的本地的图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
copyOption	CopyOptions	设置图片是否可复制。 当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。 默认值：CopyOptions.None 说明： svg图片不支持复制。 当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
colorFilter	ColorFilter	给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。 矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。 RGBA值分别是0和1之间的浮点数字，当矩阵对角线值为1时，保持图片原有色彩。 计算规则： 如果输入的滤镜矩阵为： 像素点为[R, G, B, A] 则过滤后的颜色为 [R’, G’, B’, A’]

说明：

• 使用快捷组合键对Image组件复制时，Image组件必须处于获焦状态。Image组件默认不获焦，需将focusable属性设置为true，即可使用TAB键将焦点切换到组件上，再将focusOnTouch属性设置为true，即可实现点击获焦。
• 图片设置为svg图源时，当前支持的标签是svg、rect、circle、ellipse、path、line、polyline和polygon。

ImageInterpolation

从API version 10开始，该接口支持在ArkTS卡片中使用。

名称	描述
None	不使用图片插值。
High	高图片插值，插值质量最高，可能会影响图片渲染的速度。
Medium	中图片插值。
Low	低图片插值。

ImageRenderMode

从API version 10开始，该接口支持在ArkTS卡片中使用。

名称	描述
Original	原色渲染模式。
Template	黑白渲染模式。

DrawableDescriptor²³⁺

type DrawableDescriptor = DrawableDescriptor

作为Image组件的入参对象。

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

支持平台： Android、iOS

类型	说明
DrawableDescriptor	返回一个DrawableDescriptor对象。

事件

除支持通用事件外，还支持以下事件：

onComplete

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

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

参数：

参数名	类型	说明
width	number	图片的宽。 单位：像素
height	number	图片的高。 单位：像素
componentWidth	number	组件的宽。 单位：像素
componentHeight	number	组件的高。 单位：像素
loadingStatus	number	图片加载成功的状态值。 说明： 返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。
contentWidth	number	图片实际绘制的宽度。 单位：像素 说明： 仅在loadingStatus返回1时有效。
contentHeight	number	图片实际绘制的高度。 单位：像素 说明： 仅在loadingStatus返回1时有效。
contentOffsetX	number	实际绘制内容相对于组件自身的x轴偏移。 单位：像素 说明： 仅在loadingStatus返回1时有效。
contentOffsetY	number	实际绘制内容相对于组件自身的y轴偏移。 单位：像素 说明： 仅在loadingStatus返回1时有效。

onError

onError(callback: (event?: { componentWidth: number, componentHeight: number , message: string }) => void)

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

参数：

参数名	类型	说明
componentWidth	number	组件的宽。 单位：像素
componentHeight	number	组件的高。 单位：像素
message	string	报错信息。

onFinish

onFinish(event: () => void)

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

仅支持svg格式的图片。

示例

加载基本类型图片

@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 })
  }
}

加载网络图片

加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。如果需要更灵活的网络配置，可以使用HTTP工具包发送网络请求，接着将返回的数据解码为Image组件中的PixelMap，图片开发可参考图片处理。

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

@Entry
@Component
struct ImageExample2 {
  build() {
    Column({ space: 10 }) {
      Image("https://www.example.com/xxx.png")// 直接加载网络地址，请填写一个具体的网络图片地址
        .alt($r('app.media.icon'))// 使用alt，在网络图片加载成功前使用占位图
        .width(100)
        .height(100)
    }
  }
}

为图片添加事件

class tmp{
  width: number = 0
  height: number = 0
}
let msg:tmp = new tmp()
@Entry
@Component
struct ImageExample3 {
  @State widthValue: number = 0;
  @State heightValue: number = 0;
  private on: Resource = $r('app.media.image_on');
  private off: Resource = $r('app.media.image_off');
  private on2off: Resource = $r('app.media.image_on2off');
  private off2on: Resource = $r('app.media.image_off2on');
  @State src: Resource = this.on;

  build() {
    Column() {
      Row({ space: 20 }) {
        Column() {
          Image($r('app.media.img_example1'))
            .alt($r('app.media.ic_public_picture'))
            .sourceSize({
              width: 900,
              height: 900
            })
            .objectFit(ImageFit.Cover)
            .height(180).width(180)
            // 图片加载完成后，获取图片尺寸。
            .onComplete(msg => {
              if(msg){
                this.widthValue = msg.width
                this.heightValue = msg.height
              }
            })
            .onError(() => {
              console.log('load image fail')
            })
            .overlay('\nwidth: ' + String(this.widthValue) + ' height: ' + String(this.heightValue), {
              align: Alignment.Bottom,
              offset: { x: 0, y: 20 }
            })
        }
        // 为图片添加点击事件，点击完成后加载特定图片
        Image(this.src)
          .width(120).height(120)
          .onClick(() => {
            if (this.src == this.on || this.src == this.off2on) {
              this.src = this.on2off
            } else {
              this.src = this.off2on
            }
          })
          .onFinish(() => {
            if (this.src == this.off2on) {
              this.src = this.on
            } else {
              this.src = this.off
            }
          })
      }
    }.width('100%')
  }
}

播放PixelMap数组动画

该示例通过AnimatedDrawableDescriptor对象播放PixelMap数组动画。

import { AnimationOptions, AnimatedDrawableDescriptor } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct ImageExample {
  pixelMaps: PixelMap[] = [];
  @State options: AnimationOptions = { iterations: 1 };
  @State animated: AnimatedDrawableDescriptor | undefined = undefined;

  async aboutToAppear() {
    this.pixelMaps = await this.getPixelMaps();
    this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options);
  }

  build() {
    Column() {
      Row() {
        Image(this.animated)
          .width('500px').height('500px')
          .onFinish(() => {
            console.info('finish');
          })
      }.height('50%')

      Row() {
        Button('once').width(100).padding(5).onClick(() => {
          this.options = { iterations: 1 };
          this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options);
        }).margin(5)
        Button('infinite').width(100).padding(5).onClick(() => {
          this.options = { iterations: -1 };
          this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options);
        }).margin(5)
      }
    }.width('50%')
  }

  private async getPixmapListFromMedia(resource: Resource) {
    let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id);
    let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength));
    let createPixelMap: image.PixelMap[] = await imageSource.createPixelMapList({
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    });
    await imageSource.release();
    return createPixelMap;
  }

  private async getPixmapFromMedia(resource: Resource) {
    let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id);
    let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength));
    let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
    });
    await imageSource.release();
    return createPixelMap;
  }

  private async getPixelMaps() {
    // $r('app.media.mountain')需要替换为开发者所需的图像资源文件。
    let myPixelMaps: PixelMap[] = await this.getPixmapListFromMedia($r('app.media.mountain')); //添加图片
    // $r('app.media.sky')需要替换为开发者所需的图像资源文件。
    myPixelMaps.push(await this.getPixmapFromMedia($r('app.media.sky')));
    // $r('app.media.clouds')需要替换为开发者所需的图像资源文件。
    myPixelMaps.push(await this.getPixmapFromMedia($r('app.media.clouds')));
    // $r('app.media.landscape')需要替换为开发者所需的图像资源文件。
    myPixelMaps.push(await this.getPixmapFromMedia($r('app.media.landscape')));
    return myPixelMaps;
  }
}