ArkTS Image图片组件的用法（附带实例）

开发者经常需要在应用中显示各种图片，例如按钮中的图标（icon）、网络图片、本地图片等。要在应用中显示图片，可以使用图片组件 Image。Image 支持多种图片格式，包括 .png、.jpg、.bmp、.svg、.gif 和 .heif。

Image 通过调用接口来创建，接口调用形式如下：

Image(src: PixelMap | ResourceStr | DrawableDescriptor)

该接口通过图片数据源获取图片，支持本地图片和网络图片的渲染展示。其中，src 是图片的数据源。

Image 支持加载存档图和多媒体像素图两种类型。

存档图类型数据源

存档图类型的数据源可以分为本地资源、网络资源、Resource 资源、媒体库资源和 base64。

1) 本地资源

在本地 ets 文件夹下的任意位置放入图片，通过 Image 组件引入本地图片路径，即可显示图片（根目录为 ets 文件夹）。

示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Row() {
      // 此时需要在src/main/ets下有一个myimgs文件夹，其中有一幅view.jpg的图片
      Image('myimgs/view.jpg').width(200)
    }.width('100%').padding({ left: 20, right: 20 })
  }
}

显示效果如下图所示：

2) 网络资源

引入网络图片需申请权限 ohos.permission.INTERNET。此时，Image 组件的 src 参数为网络图片的链接。

注意，当前 Image 组件仅支持加载简单的网络图片。

在 module.json5 中申请 INTERNET 权限，示例代码如下：

{
  "module": {
    // 此处仅给出关键代码
    "requestPermissions": [
      {
        name: "ohos.permission.INTERNET"
      }
    ],
    // ...
  }
}

首次加载网络图片时，Image 组件需要请求网络资源；非首次加载时，默认从缓存中直接读取图片。如果需要对缓存进行更全面的控制，可以参考 setImageCacheCount、setImageRawDataCacheSize 和 setImageFileCacheSize 接口。然而，这三个图片缓存接口并不灵活，且后续不继续演进。因此，对于复杂情况，推荐使用 ImageKnife。

加载网络图片的示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Row() {
      // 此处填写图片的地址
      Image('https://img1.baidu.com/it/u=3144466458,3149536198&fm=253&fmt=auto&app=138&f=JPEG?w=715&h=475')
        .width(200)
    }.width('100%').padding({ left: 20, right: 20 })
  }
}

显示效果如下图所示：

3) Resource资源

使用资源格式可以跨包/跨模块引入图片，resources 文件夹下的图片可以通过 $r 资源接口读取并转换为 Resource 格式。资源存放位置如下图所示：


resources 下的图片调用方式的示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Row() {
      // 设置组件显示的图片
      Image($r('app.media.view1')).width(200)
    }.width('100%').padding({ left: 20, right: 20 })
  }
}

显示效果如下图所示：


还可以将图片放在 rawfile 文件夹下，如下图所示：


rawfile 下的图片调用方式的示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
   Row() {
     Image($rawfile('view2.jpg')).width(200)
   }.width('100%').padding({ left: 20, right: 20 })
  }
}

显示效果如下图所示：


媒体库 file://data/storage 示例代码如下，支持“file://”路径前缀的字符串，用于访问通过选择器提供的图片路径。需要调用接口获取媒体库的照片 URL。

// 导入所需模块
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct ImageSample {
  // 图片列表
  @State imgDatas: string[] = [];

  // 获取照片 URL 集合
  async getAllImg() {
    try {
      // 挑选图片的选项
      let photoSelectOptions: photoAccessHelper.PhotoSelectOptions =
        new photoAccessHelper.PhotoSelectOptions();

      // 图片类型：仅图片
      photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;

      // 最多选择 5 幅图片
      photoSelectOptions.maxSelectNumber = 5;

      // 图片挑选器
      let photoPicker: photoAccessHelper.PhotoViewPicker =
        new photoAccessHelper.PhotoViewPicker();

      // 根据条件选择图片
      photoPicker.select(photoSelectOptions)
        .then((photoSelectResult: photoAccessHelper.PhotoSelectResult) => {
          // 读取到图片数据后，获取图片的 uri 字符串集合，并赋值给 imgDatas
          this.imgDatas = photoSelectResult.photoUris;

          // 在控制台打印信息
          console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: '
            + JSON.stringify(photoSelectResult));
        })
        .catch((err: Error) => {
          const message = (err as BusinessError).message;
          const code = (err as BusinessError).code;
          // 如果图片挑选失败，则在控制台打印错误信息
          console.error(`PhotoViewPicker.select failed with code: ${code}, message: ${message}`);
        });
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      console.error(`PhotoViewPicker failed with code: ${code}, message: ${message}`);
    }
  }

  // 在组件即将出现时调用上述函数，获取媒体库的所有图片 URL，存入 imgDatas
  async aboutToAppear() {
    await this.getAllImg();
  }

  build() {
    Column() {
      Grid() {
        ForEach(this.imgDatas, (item: string) => {
          GridItem() {
            // 使用 imgDatas 中的 URL 加载图片
            Image(item)
              .width(150)
              .height(150)
              .objectFit(ImageFit.Contain);
          }
        }, (item: string) => JSON.stringify(item));
      }
    }
    .width('100%')
    .height('100%');
  }
}

显示效果如下图所示：


从媒体库获取的 URL 格式通常如下：

Image('file://media/Photo/2/IMG_1735624071_001/IMG_001.jpg').width(200)

4) base64

base64 的路径格式为：

data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data]

其中 [base64 data] 为 Base64 字符串数据。Base64 格式字符串常用于存储图片的像素数据，在网页上应用较为广泛。

Image组件添加属性

给 Image 组件设置属性，可以使图片显示更加灵活，达到一些自定义的效果。以下是几个常用属性的使用示例。

1) 设置图片缩放类型

通过 objectFit 属性使图片缩放到指定的高度和宽度，示例代码如下：

@Entry
@Component
struct ImageSample {
  scroller: Scroller = new Scroller();

  build() {
    Scroll(this.scroller) {
      Column() {
        Row() {
          Image($r('app.media.view1'))
            .width(80)
            .height(40)
            .border({ width: 1 })
            // 保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内
            .objectFit(ImageFit.Contain)
            .margin(15)
            .overlay('Contain', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

          Image($r('app.media.view1'))
            .width(80)
            .height(40)
            .border({ width: 1 })
            // 保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界
            .objectFit(ImageFit.Cover)
            .margin(15)
            .overlay('Cover', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

          Image($r('app.media.view1'))
            .width(80)
            .height(40)
            .border({ width: 1 })
            // 自适应显示
            .objectFit(ImageFit.Auto)
            .margin(15)
            .overlay('Auto', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });
        }

        Row() {
          Image($r('app.media.view1'))
            .width(80)
            .height(40)
            .border({ width: 1 })
            // 不保持宽高比进行放大或缩小，使得图片充满显示边界
            .objectFit(ImageFit.Fill)
            .margin(15)
            .overlay('Fill', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

          Image($r('app.media.view1'))
            .width(80)
            .height(40)
            .border({ width: 1 })
            // 保持宽高比显示，图片缩小或者保持不变
            .objectFit(ImageFit.ScaleDown)
            .margin(15)
            .overlay('ScaleDown', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

          Image($r('app.media.view1'))
            .width(80)
            .height(40)
            .border({ width: 1 })
            // 保持原有尺寸显示
            .objectFit(ImageFit.None)
            .margin(15)
            .overlay('None', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });
        }
      }
    }
  }
}

显示效果如下图所示：

2) 图片插值

当原图分辨率较低并且放大显示时，图片会变模糊且出现锯齿。这时，可以使用 interpolation 属性对图片进行插值，从而使图片显示得更清晰。

插值是通过已有的像素值来计算新的像素值。常见的插值方法包括最近邻插值、双线性插值、立方插值等。图片插值示例如下：

@Entry
@Component
struct ImageSample {
  build() {
    Column() {
      Row() {
        Image($r('app.media.view3'))
          .width('40%')
          .interpolation(ImageInterpolation.None) // 禁用图像插值
          .borderWidth(1)
          .overlay('Interpolation.None', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
          .margin(10);

        Image($r('app.media.view3'))
          .width('40%')
          .interpolation(ImageInterpolation.Low) // 使用低质量的插值算法
          .borderWidth(1)
          .overlay('Interpolation.Low', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
          .margin(10);
      }
      .width('100%')
      .justifyContent(FlexAlign.Center);

      Row() {
        Image($r('app.media.view3'))
          .width('40%')
          .interpolation(ImageInterpolation.Medium) // 使用中等质量的插值算法
          .borderWidth(1)
          .overlay('Interpolation.Medium', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
          .margin(10);

        Image($r('app.media.view3'))
          .width('40%')
          .interpolation(ImageInterpolation.High) // 使用高质量的插值算法
          .borderWidth(1)
          .overlay('Interpolation.High', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
          .margin(10);
      }
      .width('100%')
      .justifyContent(FlexAlign.Center);
    }
    .height('100%');
  }
}

显示效果如下图所示：

3) 设置图片重复样式

通过 objectRepeat 属性可以设置图片重复的方式，示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Column({ space: 10 }) {
      Row({ space: 5 }) {
        Image($r('app.media.ic_public_favor_filled_1'))
          .width(110)
          .height(115)
          .border({ width: 1 })
          // 在水平轴和竖直轴上同时重复绘制图片
          .objectRepeat(ImageRepeat.XY)
          .objectFit(ImageFit.ScaleDown)
          .overlay('ImageRepeat.XY', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

        Image($r('app.media.ic_public_favor_filled_1'))
          .width(110)
          .height(115)
          .border({ width: 1 })
          // 只在竖直轴上重复绘制图片
          .objectRepeat(ImageRepeat.Y)
          .objectFit(ImageFit.ScaleDown)
          .overlay('ImageRepeat.Y', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

        Image($r('app.media.ic_public_favor_filled_1'))
          .width(110)
          .height(115)
          .border({ width: 1 })
          // 只在水平轴上重复绘制图片
          .objectRepeat(ImageRepeat.X)
          .objectFit(ImageFit.ScaleDown)
          .overlay('ImageRepeat.X', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });
      }

    }
     .height(150)
     .width('100%')
     .padding(8);
  }
}

显示效果如下图所示：

4) 设置图片渲染模式

通过 renderMode 属性可以设置图片的渲染模式为原色或黑白，示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Column({ space: 10 }) {
      Row({ space: 50 }) {
        Image($r('app.media.startIcon'))
          // 设置图片的渲染模式为原色
          .renderMode(ImageRenderMode.Original)
          .width(100)
          .height(100)
          .border({ width: 1 })
          // overlay 是通用属性，用于在组件上显示说明文字
          .overlay('Original', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });

        Image($r('app.media.startIcon'))
          // 设置图片的渲染模式为黑白
          .renderMode(ImageRenderMode.Template)
          .width(100)
          .height(100)
          .border({ width: 1 })
          .overlay('Template', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });
      }
      .height(150)
      .width('100%')
      .padding({ top: 20, right: 10 });
    }
  }
}

显示效果如下图所示：

5) 设置图片解码尺寸

通过 sourceSize 属性可以设置图片解码尺寸，从而降低图片的分辨率。例如，原图尺寸为 1280×960 像素，可以将图片解码为 40×40 像素和 90×90 像素，示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Column() {
      Row({ space: 50 }) {
        Image($r('app.media.view4'))
          // 设置图片新的分辨率
          .sourceSize({
            width: 40,
            height: 40
          })
          // 图片比例保持不变，进行缩放以适应 sourceSize 的设置
          .objectFit(ImageFit.ScaleDown)
          .aspectRatio(1)
          .width('25%')
          .border({ width: 1 })
          .overlay('width:40 height:40', { align: Alignment.Bottom, offset: { x: 0, y: 40 } });

        Image($r('app.media.view4'))
          // 设置图片新的分辨率
          .sourceSize({
            width: 90,
            height: 90
          })
          // 图片比例保持不变，进行缩放以适应 sourceSize 的设置
          .objectFit(ImageFit.ScaleDown)
          .aspectRatio(1)
          .width('25%')
          .border({ width: 1 })
          .overlay('width:90 height:90', { align: Alignment.Bottom, offset: { x: 0, y: 40 } });
      }
      .height(150)
      .width('100%')
      .padding(20);
    }
  }
}

显示效果如下图所示：

6) 为图片添加滤镜效果

通过 colorFilter 属性可以修改图片的像素颜色，为图片添加滤镜，示例代码如下：

@Entry
@Component
struct ImageSample {
  build() {
    Column() {
      Row() {
        Image($r('app.media.view4'))
          .width('40%')
          .margin(10);

        Image($r('app.media.view4'))
          .width('40%')
          // 设置 4×5 颜色矩阵滤镜，将图片处理为黄色调
          .colorFilter([
            1, 1, 0, 0, 0,
            0, 1, 0, 0, 0,
            0, 0, 1, 0, 0,
            0, 0, 0, 1, 0
          ])
          .margin(10);
      }
      .width('100%')
      .justifyContent(FlexAlign.Center);
    }
  }
}

显示效果如下图所示：

7) 同步加载图片

通常情况下，图片加载是异步进行的，以避免阻塞主线程，影响 UI 交互。然而，在某些情况下，图片刷新时可能会出现闪烁。此时，可以使用 syncLoad 属性使图片同步加载，从而避免出现闪烁。

需要注意的是，当图片加载的时间较长时，不建议使用该属性，因为它可能会导致页面无法响应。

Image($r('app.media.icon')).syncLoad(true)

事件调用

通过在 Image 组件上绑定 onComplete 事件，可以在图片加载成功后获取图片的必要信息。如果图片加载失败，也可以通过绑定 onError 回调来获得错误信息。示例代码如下：

@Entry
@Component
struct ImageSample {
  @State widthValue: number = 0;
  @State heightValue: number = 0;
  @State componentWidth: number = 0;
  @State componentHeight: number = 0;

  img_path: string = 'fake path';

  build() {
    Column() {
      Row() {
        Image($r('app.media.view4'))
          // Image($r(this.img_path))   // 可替换为实际路径
          .width(200)
          .height(150)
          .margin(15)
          // 图片加载成功回调：获取原始宽高及组件宽高
          .onComplete((msg) => {
            if (msg) {
              this.widthValue = msg.width;
              this.heightValue = msg.height;
              this.componentWidth = msg.componentWidth;
              this.componentHeight = msg.componentHeight;
            }
          })
          // 图片获取失败时打印信息
          .onError(() => {
            console.info('load image fail');
          })
          // 在图片下方显示尺寸信息
          .overlay(
            `\nwidth: ${this.widthValue}, height: ${this.heightValue}\n` +
            `componentWidth: ${this.componentWidth}\n` +
            `componentHeight: ${this.componentHeight}`,
            {
              align: Alignment.Bottom,
              offset: { x: 0, y: 60 }
            }
          );
      }
    }
  }
}

正常显示效果如下图所示：


如果图片加载失败，则在控制台输出如下图所示的信息：