openharmony 鸿蒙 arkts-apis-image-ExifMetadata

2026-08-25 浏览 (1)

Class (ExifMetadata)

ExifMetadata implements Metadata

Exif（Exchangeable image file format）元数据。

说明：

本模块首批接口从API version 23开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { image } from '@kit.ImageKit';

属性

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

各属性详细取值，请参考PropertyKey。

名称类型只读可选说明
newSubfileTypenumber否是表示该子文件的数据类型（例如文本/图像等基本类型，而非具体存储格式）。
subfileTypenumber否是已弃用标签，表示该子文件中的数据类型。请使用newSubfileType替代。
imageWidthnumber否是图像宽度。单位为像素（px）。
imageLengthnumber否是图像长度。单位为像素（px）。
bitsPerSamplenumber[]否是像素各分量的位数。如RGB是3分量，格式是8，8，8。
compressionnumber否是用于图像压缩的算法标准。
photometricInterpretationnumber否是像素组成，如RGB（红绿蓝，Red Green Blue）和YCbCr（亮度-蓝色色差-红色色差，Luma-Chrominance）。
imageDescriptionstring否是图像描述。
makestring否是拍摄设备的品牌制造商名称。
modelstring否是相机型号。
stripOffsetsnumber[]否是图像数据的分块存储偏移量，单位为字节。
为提高大图像访问效率，原始像素数据被分割为多个连续区块（称为条带）。
此标签按顺序存储每个条带在文件中的起始位置偏移量。
orientationOrientation否是图像方向。
samplesPerPixelnumber否是记录每个像素的颜色分量数量，适用于RGB（红绿蓝，Red Green Blue）和YCbCr（亮度-蓝色色差-红色色差，Luma-Chrominance）色彩模型。
由于这两种模型都是三分量模型（一个亮度分量加两个色度分量，或三个颜色通道），因此该标签的标准值为3。
对于JPEG压缩图像，此标签将会被对应的JPEG标记替换。
rowsPerStripnumber否是每条图像数据的行数。
stripByteCountsnumber[]否是压缩后每个条带中的字节数。
xResolutionnumber否是宽度方向上的图像分辨率。
yResolutionnumber否是高度方向上的图像分辨率。
planarConfigurationnumber否是指示像素分量是以块状或平面格式记录。
resolutionUnitnumber否是用于测量宽度方向上的图像分辨率和高度方向上的图像分辨率的单位。
transferFunctionstring否是图像的传递函数，通常用于颜色校正。
softwarestring否是用于生成图像的软件名称和版本。
dateTimestring否是图像创建的日期和时间。
在本标准中，指文件更改的日期和时间。格式为：“YYYY:MM:DD HH:MM:SS”，时间以24小时格式显示。例如：“2025:12:15 18:44:59”。
artiststring否是创建图像的人的姓名。
whitePointnumber[]否是图像白点的色度。
primaryChromaticitiesnumber[]否是图像原色的色度。
photoModenumber否是照片模式。
jpegInterchangeFormatnumber否是JPEG交换格式比特流的SOI（Start of Image）标记。
jpegInterchangeFormatLengthnumber否是JPEG流的字节数。
yCbCrCoefficientsnumber[]否是用于将RGB图像数据转换为YCbCr图像数据的变换矩阵系数。
yCbCrSubSamplingnumber[]否是色度分量与亮度分量的采样比。
yCbCrPositioningnumber否是色度分量相对于亮度分量的位置。
referenceBlackWhitenumber[]否是参考黑点值和白点值。
copyrightstring否是图像的版权信息。
exposureTimenumber否是曝光时间。单位为秒（s）。
fNumbernumber否是光圈值，如f/1.8。
exposureProgramnumber否是相机在拍摄照片时用于设置曝光的程序类。
spectralSensitivitystring否是指示相机每个通道的光谱灵敏度。
gpsVersionIDnumber[]否是GPS信息的格式版本标识符。
gpsLatitudeRefstring否是GPS纬度参考。例如，N表示北纬，S表示南纬。
gpsLatitudenumber[]否是GPS纬度。
纬度用三个RATIONAL（分数形式存储的数值）值表示，分别是度、分和秒，格式为dd/1、mm/1、ss/1。
当使用度数和分钟时，分钟分数最多保留两位小数，格式为dd/1，mmmm/100,0/1。
gpsLongitudeRefstring否是GPS经度参考。例如，E表示东经，W表示西经。
gpsLongitudenumber[]否是GPS经度。
经度用三个RATIONAL（分数形式存储的数值）值表示，分别是度、分和秒，格式为dd/1、mm/1、ss/1。
当使用度数和分钟时，分钟分数最多保留两位小数，格式为dd/1，mmmm/100，0/1。
gpsAltitudeRefnumber否是用于GPS的参考高度。
gpsAltitudenumber否是基于GPSAltitudeRef中的参考高度。
gpsTimestampnumber[]否是GPS时间戳。
gpsSatellitesstring否是用于测量的GPS卫星。通常是它的伪随机噪声码（PRN）编号。
gpsStatusstring否是记录图像时GPS接收器的状态。
gpsMeasureModestring否是GPS测量模式。
gpsDopnumber否是GPS数据精度DOP精度衰减因子（Dilution of Precision）。
gpsSpeedRefstring否是GPS接收器移动速度的单位。
gpsSpeednumber否是GPS接收器移动的速度。
gpsTrackRefstring否是提供GPS接收机运动方向的参考。
gpsTracknumber否是GPS接收器移动的方向。
gpsImgDirectionRefstring否是图像方向的参考。
gpsImgDirectionnumber否是拍摄时图像的方向。
gpsMapDatumstring否是GPS接收机使用的大地测量数据。
gpsDestLatitudeRefstring否是指示目标点的纬度参考。
gpsDestLatitudenumber[]否是目的地的纬度。
gpsDestLongitudeRefstring否是指示目标点的经度参考。
gpsDestLongitudenumber[]否是目的地的经度。
gpsDestBearingRefstring否是指向目的地的方位参考。
gpsDestBearingnumber否是到达目的地的方位。
gpsDestDistanceRefstring否是到目标点距离的测量单位。
gpsDestDistancenumber否是到目的地的距离。
gpsProcessingMethodstring否是记录定位方法的名称。
gpsAreaInformationstring否是GPS区域名称的字符串。
gpsDateStampstring否是GPS日期戳。
gpsDifferentialnumber否是是否对GPS数据应用了差分校正，这对精确定位精度至关重要。
gpsHPositioningErrornumber否是水平定位误差。单位为米（m）。
isoSpeedRatingsnumber否是ISO 12232中指定的相机或输入设备的ISO速度和ISO纬度。
photographicSensitivitynumber[]否是拍摄图像时相机或输入设备的灵敏度。
oecfArrayBuffer否是ISO 14524中规定的光电转换函数（OECF）。
sensitivityTypenumber否是灵敏度类型。
standardOutputSensitivitynumber否是标准输出灵敏度。
recommendedExposureIndexnumber否是GPS测量模式。
isoSpeedLatitudeyyynumber否是表示相机传感器在单次曝光中可记录的最大动态范围。单位为EV。
isoSpeedLatitudezzznumber否是表示相机传感器在过曝方向保护高光细节的能力边界。单位为EV。
exifVersionstring否是支持的Exif标准的版本。
dateTimeOriginalstring否是生成原始图像数据的日期和时间。
对于DSC（Digital Still Camera 数码静态相机），会记录拍摄照片的日期和时间。格式为“YYYY:MM:DD HH:MM:SS”，时间以24小时格式显示。
dateTimeDigitizedstring否是将图像作为数字数据存储的日期和时间。
例如，如果DSC捕获了图像，并同时记录了文件，则DateTimeOriginal和DateTimeDigitized将具有相同的内容。格式为“YYYY:MM:DD HH:MM:SS”，时间以24小时格式显示。
offsetTimestring否是作为DateTime标签的补充元数据，解决因地理时区变化导致的时间戳歧义问题。
offsetTimeOriginalstring否是设备的地理时区位置。
offsetTimeDigitizedstring否是记录图像数字化时的UTC协调世界时（Coordinated Universal Time）偏移，有助于精确调整时间戳。
componentsConfigurationstring否是压缩数据的信息。
compressedBitsPerPixelnumber否是图像压缩方案。单位为每像素比特。
shutterSpeedValuenumber否是快门速度，表示为摄影曝光相加系统值APEX（Additive System of Photographic Exposure）。
apertureValuenumber否是镜头光圈。单位为APEX。
brightnessValuenumber否是图像的亮度值。单位为APEX。
exposureBiasValuenumber否是曝光偏差值。
maxApertureValuenumber否是镜头的最小光圈值。
subjectDistancenumber否是拍照设备到被摄体的距离。单位为米（m）。
meteringModenumber否是测光模式。
lightSourcenumber否是光源。
flashnumber否是闪光。
focalLengthnumber否是焦距。单位为毫米。
subjectAreanumber[]否是用于指示主要对象在整个场景中的位置和区域。
makerNoteArrayBuffer否是Exif/相机文件系统设计规则DCF（Design rule for Camera File system）写入器制造商记录所需信息的标签。
userCommentstring否是用户评论。
subsecTimestring否是记录DateTime标记的秒分数的标记。
subsecTimeOriginalstring否是记录DateTimeOriginal标记的秒数。
subsecTimeDigitizedstring否是记录DateTimeDigitized标记的秒数。
flashpixVersionstring否是FPXR（FlashPix Extension Resource）支持的FlashPix格式版本，用于增强设备兼容性。
colorSpacenumber否是颜色空间信息标签，通常记录为颜色空间说明符。
pixelXDimensionnumber否是图像在X轴上的（二维坐标系中的Horizontal Axis）尺寸。单位为像素（px）。
pixelYDimensionnumber否是图像在Y轴上的（二维坐标系中的Vertical Axis）尺寸。单位为像素（px）。
relatedSoundFilestring否是与图像数据相关的音频文件的名称。
flashEnergynumber否是图像捕获时的闪光灯能量。单位为光束烛光秒（BCPS，Beam Candlepower Seconds）。
spatialFrequencyResponseArrayBuffer否是相机或输入设备空间频率表。
focalPlaneXResolutionnumber否是传感器物理平面X轴方向上每单位物理长度的像素数量。
focalPlaneYResolutionnumber否是传感器物理平面Y轴方向上每单位物理长度的像素数量。
focalPlaneResolutionUnitnumber否是FocalPlaneXResolution和FocalPlaneYResolution的测量单位。
subjectLocationnumber[]否是图像中主体的像素坐标（基于左上角原点）。
exposureIndexnumber否是拍摄时选定的曝光指数。
sensingMethodnumber否是摄像头的图像传感器类型。
fileSourceArrayBuffer否是指示图像源。
sceneTypeArrayBuffer否是场景类型。
cfaPatternArrayBuffer否是图像传感器的滤色器阵列CFA（Color Filter Array）几何图案。
customRenderednumber否是表示对图像数据的特殊处理，如HDR合成、AI场景增强。
exposureModenumber否是曝光模式。
whiteBalancenumber否是白平衡。
digitalZoomRationumber否是拍摄时的数字变焦比。
focalLengthIn35mmFilmnumber否是换算成35mm等效焦距。单位为毫米（mm）。
sceneCaptureTypenumber否是拍摄的场景类型。
gainControlnumber否是整体图像增益调整程度。
contrastnumber否是相机应用的对比度优化策略。例如：标准处理、弱化对比度等。
saturationnumber否是相机应用的色彩饱和度调节策略。例如：标准、降饱和模式等。
sharpnessnumber否是相机应用的边缘增强处理方式。例如：弱锐化、标准锐化等。
deviceSettingDescriptionArrayBuffer否是特定相机型号的拍照条件信息。
subjectDistanceRangenumber否是指示到对象的距离范围。
imageUniqueIdstring否是为每个图像分配的唯一标识符。
cameraOwnerNamestring否是相机所有者的姓名。
bodySerialNumberstring否是相机机身的序列号。
lensSpecificationnumber[]否是所用镜头的规格。
lensMakestring否是镜头的制造商。
lensModelstring否是镜头的型号名称。
lensSerialNumberstring否是镜头的序列号。
compositeImagenumber否是指示图像是否为合成图像。
sourceImageNumberOfCompositeImagenumber[]否是用于合成图像的源图像数量。
sourceExposureTimesOfCompositeImageArrayBuffer否是合成图像的源图像的曝光时间，例如1/33秒。
gammanumber否是每个组件的伽玛值。

createInstance

static createInstance(): ExifMetadata

创建一个空的ExifMetadata实例。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型说明
ExifMetadata返回ExifMetadata的空实例。

示例：

async function exifMetadataCreateInstance(context: Context) {
  let exifMetadata = image.ExifMetadata.createInstance();
  if (exifMetadata != undefined) {
    console.info("createInstance success");
  }
}

getProperties

getProperties(key: Array<string>): Promise<Record<string, string |null>>

获取图像的元数据属性值。使用Promise异步回调。

要查询的属性的具体信息请参考PropertyKey。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名类型必填说明
keyArray<string>是要获取的值的属性名称。

返回值：

类型说明
Promise<Record<string, string |null>>Promise对象，返回获取到的图像元数据属性值。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID错误信息
7600202Unsupported metadata. Possible causes: unsupported metadata type.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';

function getFileFd(context: Context): number|undefined {
  const filePath: string = context.cacheDir + '/exif.jpg';  // 图片包含exif metadata。
  const file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
  const fd: number = file?.fd;
  return fd;
}

async function exifMetadataGetProperties(context: Context) {
  let fd = getFileFd(context);
  let imageSource = image.createImageSource(fd);
  let metaData = await imageSource.readImageMetadata(["ImageWidth", "ImageLength"]);
  if (metaData != undefined && metaData.exifMetadata != undefined) {
    await metaData.exifMetadata.getProperties(["ImageWidth", "ImageLength"]).then((data) => {
      console.info('Get properties ',JSON.stringify(data));
    }).catch((error: BusinessError) => {
      console.error(`Get properties failed error.code is ${error.code}, error.message is ${error.message}`);
    });
  } else {
    console.error('Metadata is null.');
  }
}

setProperties

setProperties(records: Record<string, string |null>): Promise<void>

批量设置图片元数据中的指定属性的值。使用Promise异步回调。

要查询的属性的具体信息请参考PropertyKey。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名类型必填说明
recordsRecord<string, string |null>是用户要修改的ExifMetadata对象的属性和键值对的集合。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID错误信息
7600202Unsupported metadata. Possible causes: unsupported metadata type.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';

function getFileFd(context: Context): number|undefined {
  const filePath: string = context.cacheDir + '/exif.jpg';  // 图片包含exif metadata。
  const file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
  const fd: number = file?.fd;
  return fd;
}

async function exifMetadataSetProperties(context: Context) {
  let fd = getFileFd(context);
  let imageSource = image.createImageSource(fd);
  let metaData = await imageSource.readImageMetadata(["ImageWidth", "ImageLength"]);
  if (metaData != undefined && metaData.exifMetadata != undefined) {
    let setkey: Record<string, string|null> = {
      "ImageWidth": "200",
      "ImageLength": "300"
    };
    await metaData.exifMetadata.setProperties(setkey).then(async () => {
      console.info('Set properties success.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to set metadata Properties. code is ${error.code}, message is ${error.message}`);
    })
  } else {
    console.error('metadata is null. ');
  }
}

getAllProperties

getAllProperties(): Promise<Record<string, string |null>>

获取图片中所有元数据的属性和值。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型说明
Promise<Record<string, string |null>>Promise对象，返回元数据拥有的所有属性的值。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';

function getFileFd(context: Context): number|undefined {
  const filePath: string = context.cacheDir + '/exif.jpg';  // 图片包含exif metadata。
  const file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
  const fd: number = file?.fd;
  return fd;
}

async function exifMetadataGetAllProperties(context: Context) {
  let fd = getFileFd(context);
  let imageSource = image.createImageSource(fd);
  let metaData = await imageSource.readImageMetadata(["ImageWidth", "ImageLength"]);
  if (metaData != undefined && metaData.exifMetadata != undefined) {
    await metaData.exifMetadata.getAllProperties().then((data) => {
      const count = Object.keys(data).length;
      console.info('Metadata have ', count, ' properties');
      console.info(`Get metadata all properties: ${data}`);
    }).catch((error: BusinessError) => {
      console.error(`Get metadata all properties failed error.code is ${error.code}, error.message is ${error.message}`);
    });
  } else {
    console.error('Metadata is null.');
  }
}

clone

clone(): Promise<ExifMetadata>

对Exif元数据进行克隆。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型说明
Promise<ExifMetadata>Promise对象，成功返回Exif元数据实例。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';

function getFileFd(context: Context): number|undefined {
  const filePath: string = context.cacheDir + '/exif.jpg';  // 图片包含exif metadata。
  const file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
  const fd: number = file?.fd;
  return fd;
}

async function exifMetadataClone(context: Context) {
  let fd = getFileFd(context);
  let imageSource = image.createImageSource(fd);
  let metaData = await imageSource.readImageMetadata(["ImageWidth", "ImageLength"]);
  if (metaData != undefined && metaData.exifMetadata != undefined) {
    let new_metadata = await metaData.exifMetadata.clone();
    new_metadata.getProperties(["ImageWidth"]).then((data1) => {
      console.info(`Clone new_metadata and get Properties: ${data1}`);
    }).catch((err: BusinessError) => {
      console.error(`Clone new_metadata failed, error : ${err}`);
    });
  } else {
    console.error('Metadata is null.');
  }
}

getBlob

getBlob(): Promise<ArrayBuffer>

以二进制数据的形式获取元数据。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型说明
Promise<ArrayBuffer>Promise对象，返回元数据的二进制数据。

示例：

import { fileIo } from '@kit.CoreFileKit';

function getFileFd(context: Context): number|undefined {
  const filePath: string = context.cacheDir + '/exif.jpg';  // 图片包含exif metadata。
  const file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
  const fd: number = file?.fd;
  return fd;
}

async function exifMetadataGetBlob(context: Context) {
  let fd = getFileFd(context);
  let imageSource = image.createImageSource(fd);
  let metaData = await imageSource.readImageMetadata(["ImageWidth", "ImageLength"]);
  if (metaData != undefined && metaData.exifMetadata != undefined) {
    let blob = await metaData.exifMetadata.getBlob();
    if (blob != undefined) {
      console.info("get blob success");
    }
  }
}

setBlob

setBlob(blob: ArrayBuffer): Promise<void>

使用二进制数据替换当前元数据。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名类型必填说明
blobArrayBuffer是要替换的二进制数据。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID错误信息
7600206Invalid parameter. Possible causes: The blob is empty or has a length of 0.

示例：

import { fileIo } from '@kit.CoreFileKit';

function getFileFd(context: Context): number|undefined {
  const filePath: string = context.cacheDir + '/exif.jpg';  // 图片包含exif metadata。
  const file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
  const fd: number = file?.fd;
  return fd;
}

async function exifMetadataSetBlob(context: Context) {
  let fd = getFileFd(context);
  let imageSource = image.createImageSource(fd);
  let metaData = await imageSource.readImageMetadata(["ImageWidth", "ImageLength"]);
  if (metaData != undefined && metaData.exifMetadata != undefined) {
    let blob = await metaData.exifMetadata.getBlob();
    if (blob != undefined) {
      console.info("get blob success");
      metaData.exifMetadata.setBlob(blob);
    }
    let new_blob = metaData.exifMetadata.getBlob();
    if (new_blob != undefined) {
      console.info("new_blob is not undefined");
    }
  }
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-image-nativemodule-oh-pixelmap-hdrmetadatavalue

openharmony 鸿蒙 capi-image-imagepacker-opts-

openharmony 鸿蒙 capi-image-nativemodule-image-region

openharmony 鸿蒙 capi-image-imagepacker-native-

openharmony 鸿蒙 capi-image-imagenative-

openharmony 鸿蒙 capi-image-processing-h

openharmony 鸿蒙 capi-image-ohosimagesourcesupportedformat

openharmony 鸿蒙 capi-image-nativemodule-image-size

openharmony 鸿蒙 capi-image-mdk-h

openharmony 鸿蒙 capi-image-ohosimagesourcedelaytimelist

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/aU6YsLzA