# Class (XMPMetadata)

XMP（Extensible Metadata Platform）元数据。

**起始版本：** 26.0.0

#### 导入模块

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

#### XMP路径语法

XMP路径用于定位元数据中的具体标签。路径由以下语法构件组合而成：

| 语法类别 | 说明 | 示例 |
| --- | --- | --- |
| 基本属性路径 | 使用:将命名空间前缀和标签名分隔开。 | dc:title表示Dublin Core命名空间中的title字段。 |
| 数组索引 | 使用[]配合从1起始的索引值定位元素，或使用last()访问最后一个元素。 | dc:subject[2]表示第二个元素；dc:subject[last()]表示最后一个元素。 |
| 结构体成员 | 使用/指定结构体成员。 | exif:Flash/exif:Fired表示exif:Flash字段的Fired成员。 |
| 限定符访问 | 使用/?指定限定符。也常用于访问多语言文本数组中元素的语言属性。 | dc:title/?book:lastUpdated表示title的book:lastUpdated限定符；dc:title[1]/?xml:lang表示第一个多语言文本元素的语言限定符。 |
| 命名空间前缀 （仅rootPath支持） | 仅指定命名空间前缀，遍历该命名空间下所有标签。 | dc遍历Dublin Core命名空间下的全部字段。 |

#### registerXMPNamespace

registerXMPNamespace(xmpNamespace: XMPNamespace): Promise<void>

注册指定的命名空间。使用Promise异步回调。

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| xmpNamespace | XMPNamespace | 是 | XMP命名空间。 |

**返回值：**

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

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. Invalid namespace format. 2. The uri is already registered. 3. The prefix is already registered. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function RegisterNamespacePrefix() {
  try {
    let xmpMetadata = new image.XMPMetadata();
    // 注册自定义命名空间，注册后方可使用该前缀创建标签。
    let xmpNamespace: image.XMPNamespace = {uri: "urn:example:book:1.0", prefix: "book"};
    await xmpMetadata.registerXMPNamespace(xmpNamespace);
    console.info('Succeeded in registering namespace prefix.');
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to register namespace prefix! code is ${err.code}, message is ${err.message}`);
  }
}
```

#### setValue

setValue(path: string, type: XMPTagType, value?: string): Promise<void>

为指定路径下的XMP标签设置类型和值。使用Promise异步回调。

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| path | string | 是 | 目标XMP标签的路径。路径语法参见XMP路径语法。 |
| type | XMPTagType | 是 | XMP标签类型。 |
| value | string | 否 | XMP标签值。默认为空字符串。 |

**返回值：**

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

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. Namespace is not registered. 2. The path syntax is invalid. 3. The path does not match the type. 4. The value is invalid for the type. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function SetValue() {
  try {
    let xmpMetadata = new image.XMPMetadata();
    // 设置xmp:title标签的值，类型为字符串，值为'My Title'。
    // xmp为内置命名空间，无需注册即可使用。
    await xmpMetadata.setValue(`${image.XMP_BASIC.prefix}:title`, image.XMPTagType.STRING, 'My Title');
    console.info('Succeeded in setting XMP tag value.');
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to set XMP tag value! code is ${err.code}, message is ${err.message}`);
  }
}
```

#### getTag

getTag(path: string): Promise<XMPTag | null>

从指定路径获取单个XMP标签。使用Promise异步回调。

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| path | string | 是 | 目标XMP标签的路径。路径语法参见XMP路径语法。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<XMPTag \| null> | Promise对象，返回指定路径下的XMP标签。若获取失败，返回空值。 |

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. Namespace is not registered. 2. The path syntax is invalid. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function GetTag() {
  try {
    let xmpMetadata = new image.XMPMetadata();
    await xmpMetadata.setValue(`${image.XMP_BASIC.prefix}:title`, image.XMPTagType.STRING, 'My Title');
    // 获取xmp:title路径的标签。
    let tag: image.XMPTag | null = await xmpMetadata.getTag(`${image.XMP_BASIC.prefix}:title`);
    console.info(`${image.XMP_BASIC.prefix}:title: ${tag?.value}`);
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to get XMP tag! code is ${err.code}, message is ${err.message}`);
  }
}
```

#### removeTag

removeTag(path: string): Promise<void>

删除指定路径下的XMP标签。使用Promise异步回调。

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| path | string | 是 | 目标XMP标签的路径。路径语法参见XMP路径语法。 |

**返回值：**

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

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. Namespace is not registered. 2. The path syntax is invalid. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function RemoveTag() {
  try {
    let xmpMetadata = new image.XMPMetadata();
    await xmpMetadata.setValue(`${image.XMP_BASIC.prefix}:title`, image.XMPTagType.STRING, 'My Title');
    await xmpMetadata.removeTag(`${image.XMP_BASIC.prefix}:title`);
    // 再次获取验证是否已移除，如果节点不存在则返回null。
    let tag: image.XMPTag | null = await xmpMetadata.getTag(`${image.XMP_BASIC.prefix}:title`);
    console.info(`${image.XMP_BASIC.prefix}:title exists after remove: ${tag !== null}`);
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to remove XMP tag! code is ${err.code}, message is ${err.message}`);
  }
}
```

#### enumerateTags

enumerateTags(callback: (path: string, tag: XMPTag) => boolean, rootPath?: string, options?: XMPEnumerateOptions): void

枚举指定路径下的所有XMP标签。

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | (path: string, tag: XMPTag) => boolean | 是 | 同步回调函数。 返回true，表示继续遍历；返回false，表示停止遍历。 path参数是标签的唯一路径标识，遵循XMP路径语法；tag参数是对应标签的数据表示形式。 |
| rootPath | string | 否 | 遍历起始节点。默认从根节点开始，路径语法参见XMP路径语法。 |
| options | XMPEnumerateOptions | 否 | 遍历选项。 默认行为：仅遍历直接子节点，返回普通节点和限定符。 |

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. Namespace is not registered. 2. The rootPath syntax is invalid. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function EnumerateTags(imageSourceObj: image.ImageSource) {
  // 指定读取XMP类型的元数据。
  let types: image.MetadataType[] = [image.MetadataType.XMP_METADATA];
  await imageSourceObj.readImageMetadataByType(types).then((metaData: image.ImageMetadata) => {
    if (metaData != undefined && metaData.xmpMetadata != undefined) {
      try {
        // 获取所有XMP标签（递归模式、包含普通节点和限定符）。
        metaData.xmpMetadata.enumerateTags((path: string, tag: image.XMPTag): boolean => {
          // 打印标签路径、名称和值。
          console.info(`path: ${path}, name: ${tag.name}, value: ${tag.value}`);
          return true;  // 返回true继续遍历。
        }, undefined, { isRecursive: true, onlyQualifier: false });
      } catch (error) {
        let err: BusinessError = error as BusinessError;
        console.error(`EnumerateTags failed! error.code is ${err.code}, error.message is ${err.message}`);
      }
    }
  }).catch((error: BusinessError) => {
    console.error(`ReadImageMetadataByType failed! error.code is ${error.code}, error.message is ${error.message}`);
  })
}
```

#### getTags

getTags(rootPath?: string, options?: XMPEnumerateOptions): Promise<Record<string, XMPTag>>

获取指定路径下的XMP标签及其子标签。使用Promise异步回调。

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| rootPath | string | 否 | 遍历起始节点。默认从根节点开始，路径语法参见XMP路径语法。 |
| options | XMPEnumerateOptions | 否 | 遍历选项。 默认行为：仅遍历直接子节点，返回普通节点和限定符。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<Record<string, XMPTag>> | Promise对象，返回XMP标签集合。 |

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. Namespace is not registered. 2. The rootPath syntax is invalid. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function GetTags(imageSourceObj: image.ImageSource) {
  // 指定读取XMP类型的元数据。
  let types: image.MetadataType[] = [image.MetadataType.XMP_METADATA];
  await imageSourceObj.readImageMetadataByType(types).then(async (metaData: image.ImageMetadata) => {
    if (metaData != undefined && metaData.xmpMetadata != undefined) {
      try {
        // 获取所有XMP标签（递归模式、包含普通节点和限定符）。
        let tags: Record<string, image.XMPTag> =
          await metaData.xmpMetadata.getTags(undefined, { isRecursive: true, onlyQualifier: false });
        console.info(`tagCount: ${Object.keys(tags).length}`);
        console.info(JSON.stringify(tags));
      } catch (error) {
        let err: BusinessError = error as BusinessError;
        console.error(`Failed to get XMP tags! code is ${err.code}, message is ${err.message}`);
      }
    }
  }).catch((error: BusinessError) => {
    console.error(`ReadImageMetadataByType failed! error.code is ${error.code}, error.message is ${error.message}`);
  })
}
```

#### getBlob

getBlob(): Promise<ArrayBuffer>

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

**起始版本：** 26.0.0

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

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

**返回值：**

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

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600301 | Memory alloc failed. |
| 7600302 | Memory copy failed. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function GetBlob(imageSourceObj: image.ImageSource) {
  // 指定读取XMP类型的元数据。
  let types: image.MetadataType[] = [image.MetadataType.XMP_METADATA];
  await imageSourceObj.readImageMetadataByType(types).then(async (metaData: image.ImageMetadata) => {
    if (metaData != undefined && metaData.xmpMetadata != undefined) {
      try {
        let blob: ArrayBuffer = await metaData.xmpMetadata.getBlob();
        console.info(`blobLength: ${blob.byteLength}`);
      } catch (error) {
        let err: BusinessError = error as BusinessError;
        console.error(`Failed to get XMP blob! code is ${err.code}, message is ${err.message}`);
      }
    }
  }).catch((error: BusinessError) => {
    console.error(`ReadImageMetadataByType failed! error.code is ${error.code}, error.message is ${error.message}`);
  })
}
```

#### setBlob

setBlob(buffer: ArrayBuffer): Promise<void>

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

**起始版本：** 26.0.0

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| buffer | ArrayBuffer | 是 | 要替换的二进制数据。 |

**返回值：**

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

**错误码：**

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

| 错误码ID | 错误信息 |
| --- | --- |
| 7600206 | Invalid argument. Possible causes: 1. The buffer is empty or invalid. |

**示例：**

```
import { BusinessError } from '@kit.BasicServicesKit';

async function SetBlob(imageSourceObj: image.ImageSource) {
  // 指定读取XMP类型的元数据。
  let types: image.MetadataType[] = [image.MetadataType.XMP_METADATA];
  await imageSourceObj.readImageMetadataByType(types).then(async (metaData: image.ImageMetadata) => {
    if (metaData != undefined && metaData.xmpMetadata != undefined) {
      try {
        let blob: ArrayBuffer = await metaData.xmpMetadata.getBlob();
        // 以原始二进制数据回填，验证setBlob接口可用性。
        await metaData.xmpMetadata.setBlob(blob);
        let newBlob: ArrayBuffer = await metaData.xmpMetadata.getBlob();
        console.info(`newBlobLength: ${newBlob.byteLength}`);
      } catch (error) {
        let err: BusinessError = error as BusinessError;
        console.error(`Failed to set XMP blob! code is ${err.code}, message is ${err.message}`);
      }
    }
  }).catch((error: BusinessError) => {
    console.error(`ReadImageMetadataByType failed! error.code is ${error.code}, error.message is ${error.message}`);
  })
}
```