目录

使用ImageSource获取专有元数据

从API version 23开始，ImageSource陆续支持获取GIF、HEIFS、DNG、WebP、PNG、JFIF、TIFF、AVIS多种图像格式的专有元数据。

各格式支持的起始API版本如下表所示：

支持的元数据类别

元数据类别 MetadataType 返回字段 起始API版本 典型信息
GIF GIF_METADATA GifMetadata 26.0.0 帧延迟时长、循环次数、画布尺寸等。
HEIFS HEIFS_METADATA HeifsMetadata 23 画布高度、画布宽度、未钳制延迟时长等。
DNG DNG_METADATA DngMetadata 24 DNG版本号、相机型号、CFA参数、黑白电平、色彩校正矩阵等。
WebP WEBP_METADATA WebPMetadata 24 画布尺寸、帧延迟时长、循环次数等。
PNG PNG_METADATA PngMetadata 26.0.0 像素密度、描述、版权等。
JFIF JFIF_METADATA JfifMetadata 26.0.0 像素密度、渐进编码等。
TIFF TIFF_METADATA TiffMetadata 26.0.0 分辨率、色度坐标、压缩方式等。
AVIS AVIS_METADATA AvisMetadata 26.0.0 帧延迟时长等。

HeifsMetadata自API version 23起可用，其中heifsCanvasWidth、heifsCanvasHeight、heifsUnclampedDelayTime三个属性为API版本26.0.0新增。

相关接口

接口 说明
readImageMetadata

读取图像源的元数据，使用propertyKeys指定元数据字段。

从API version 23开始支持。
readImageMetadataByType

读取图像源的元数据，使用metadataTypes指定元数据类型。

从API version 24开始支持。

开发步骤

获取图片专有元数据相关API的详细介绍请参见ImageSource和Metadata。

  1. 全局导入Image模块，根据实际需求导入对应的Kit模块。

    // 导入相关模块。
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';
import { resourceManager } from '@kit.LocalizationKit';

  2. 参考使用ImageSource完成图片解码创建ImageSource实例。

  3. 读取专有元数据。

    使用readImageMetadata接口，通过指定属性键（propertyKeys）读取对应格式的专有元数据。以读取GIF元数据中的帧延迟时长为例：

    async readImageMetadata(imageSource: image.ImageSource | undefined) : Promise<image.ImageMetadata | undefined> {
  if (imageSource == undefined) {
    console.error('imageSource is undefined.');
    return undefined;
  }
  try {
    let properties: string[] = [image.GifPropertyKey.GIF_DELAY_TIME];
    let index: number = 0;
    let imageMetadata: image.ImageMetadata = await imageSource.readImageMetadata(properties, index);
    if (imageMetadata.gifMetadata != undefined) {
      console.info(`GIF_DELAY_TIME: ${JSON.stringify(imageMetadata.gifMetadata?.delayTime)}`);
    }
    return imageMetadata
  } catch (error) {
    console.error(`ReadImageMetadata failed, error.code: ${error.code},
               error.message: ${error.message}`)
    return undefined;
  }
}

    使用readImageMetadataByType接口，通过指定MetadataType枚举值读取对应格式的专有元数据。以读取GIF元数据为例：

    async readImageMetadataByType(imageSource: image.ImageSource | undefined) : Promise<image.ImageMetadata | undefined> {
  if (imageSource == undefined) {
    console.error('imageSource is undefined.');
    return undefined;
  }
  try {
    let types: image.MetadataType[] = [image.MetadataType.GIF_METADATA];
    let index: number = 0;
    let imageMetadata: image.ImageMetadata = await imageSource.readImageMetadataByType(types, index);
    if (imageMetadata.gifMetadata != undefined) {
      console.info(`GIF_DELAY_TIME: ${JSON.stringify(imageMetadata.gifMetadata?.delayTime)}`);
    }
    return imageMetadata;
  } catch (error) {
    console.error(`ReadImageMetadataByType failed, error.code: ${error.code},
               error.message: ${error.message}`)
    return undefined;
  }
}

  4. 释放imageSource。

    确认imageSource的异步方法已经执行完成，不再使用该变量后，可按需手动调用下面方法释放。

    async release() {
  try {
    await this.pixelMap?.release();
  } catch (error) {
    console.error(`Failed to release PixelMap: ${error}.`);
  } finally {
    this.pixelMap = undefined;
  }

  try {
    await this.imageSource?.release();
  } catch (error) {
    console.error(`Failed to release ImageSource: ${error}.`);
  } finally {
    this.imageSource = undefined;
  }
}

注意事项