d3f162b9创建于 2025年3月20日历史提交

@ohos.file.photoAccessHelper (相册管理模块)

该模块提供相册管理模块能力，包括创建相册以及访问、修改相册中的媒体数据信息等。

说明：

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

导入模块

import { photoAccessHelper } from '@kit.MediaLibraryKit';

photoAccessHelper.getPhotoAccessHelper

getPhotoAccessHelper(context: Context): PhotoAccessHelper

获取相册管理模块的实例，用于访问和修改相册中的媒体文件。

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。

返回值：

类型	说明
PhotoAccessHelper	相册管理模块的实例。

错误码：

接口抛出错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例：

//此处获取的phAccessHelper实例为全局对象，后续使用到phAccessHelper的地方默认为使用此处获取的对象，如未添加此段代码报phAccessHelper未定义的错误请自行添加。
let context = getContext(this);
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

PhotoAccessHelper

getAssets

getAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<PhotoAsset>>): void

获取图片和视频资源，使用callback方式返回结果。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来查询指定uri对应的图片或视频资源，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。

参数：

参数名	类型	必填	说明
options	FetchOptions	是	图片和视频检索选项。
callback	AsyncCallback<FetchResult<PhotoAsset>>	是	callback返回图片和视频检索结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getAssets');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };

  phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => {
    if (fetchResult !== undefined) {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      if (photoAsset !== undefined) {
        console.info('photoAsset.displayName : ' + photoAsset.displayName);
      }
    } else {
      console.error(`fetchResult fail with error: ${err.code}, ${err.message}`);
    }
  });
}

getAssets

getAssets(options: FetchOptions): Promise<FetchResult<PhotoAsset>>

获取图片和视频资源，使用Promise方式返回结果。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来查询指定uri对应的图片或视频资源，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。

参数：

参数名	类型	必填	说明
options	FetchOptions	是	图片和视频检索选项。

返回值：

类型	说明
Promise<FetchResult<PhotoAsset>>	Promise对象，返回图片和视频数据结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getAssets');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    if (fetchResult !== undefined) {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      if (photoAsset !== undefined) {
        console.info('photoAsset.displayName :' + photoAsset.displayName);
      }
    }
  } catch (err) {
    console.error(`getAssets failed, error: ${err.code}, ${err.message}`);
  }
}

getBurstAssets¹²⁺

getBurstAssets(burstKey: string, options: FetchOptions): Promise<FetchResult<PhotoAsset>>

获取连拍照片资源，使用Promise方式返回结果。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

参数：

参数名	类型	必填	说明
burstKey	string	是	一组连拍照片的唯一标识：uuid(可传入PhotoKeys的BURST_KEY)
options	FetchOptions	是	连拍照片检索选项。

返回值：

类型	说明
Promise<FetchResult<PhotoAsset>>	Promise对象，返回连拍照片数据结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error.

示例：

import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getBurstAssets');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  // burstKey为36位的uuid，可以根据photoAccessHelper.PhotoKeys获取。
  let burstKey: string = "e719d696-09fa-44f8-ec3f215aa62a";
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await 
      phAccessHelper.getBurstAssets(burstKey, fetchOptions);
    if (fetchResult !== undefined) {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      if (photoAsset !== undefined) {
        console.info('photoAsset.displayName :' + photoAsset.displayName);
      }
    }
  } catch (err) {
    console.error(`getBurstAssets failed, error: ${err.code}, ${err.message}`);
  }
}

createAsset

createAsset(photoType: PhotoType, extension: string, options: CreateOptions, callback: AsyncCallback<string>): void

指定待创建的文件类型、后缀和创建选项，创建图片或视频资源，使用callback方式返回结果。

此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考开发指南。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.WRITE_IMAGEVIDEO

参数：

参数名	类型	必填	说明
photoType	PhotoType	是	创建的文件类型，IMAGE或者VIDEO类型。
extension	string	是	文件名后缀参数，例如：'jpg'。
options	CreateOptions	是	创建选项，例如{title: 'testPhoto'}。
callback	AsyncCallback<string>	是	callback返回创建的图片和视频的uri。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('createAssetDemo');
  let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE;
  let extension:string = 'jpg';
  let options: photoAccessHelper.CreateOptions = {
    title: 'testPhoto'
  }
  phAccessHelper.createAsset(photoType, extension, options, (err, uri) => {
    if (uri !== undefined) {
      console.info('createAsset uri' + uri);
      console.info('createAsset successfully');
    } else {
      console.error(`createAsset failed, error: ${err.code}, ${err.message}`);
    }
  });
}

createAsset

createAsset(photoType: PhotoType, extension: string, callback: AsyncCallback<string>): void

指定待创建的文件类型和后缀，创建图片或视频资源，使用callback方式返回结果。

此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考开发指南。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.WRITE_IMAGEVIDEO

参数：

参数名	类型	必填	说明
photoType	PhotoType	是	创建的文件类型，IMAGE或者VIDEO类型。
extension	string	是	文件名后缀参数，例如：'jpg'。
callback	AsyncCallback<string>	是	callback返回创建的图片和视频的uri。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('createAssetDemo');
  let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE;
  let extension: string = 'jpg';
  phAccessHelper.createAsset(photoType, extension, (err, uri) => {
    if (uri !== undefined) {
      console.info('createAsset uri' + uri);
      console.info('createAsset successfully');
    } else {
      console.error(`createAsset failed, error: ${err.code}, ${err.message}`);
    }
  });
}

createAsset

createAsset(photoType: PhotoType, extension: string, options?: CreateOptions): Promise<string>

指定待创建的文件类型、后缀和创建选项，创建图片或视频资源，使用Promise方式返回结果。

此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考开发指南。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.WRITE_IMAGEVIDEO

参数：

参数名	类型	必填	说明
photoType	PhotoType	是	创建的文件类型，IMAGE或者VIDEO类型。
extension	string	是	文件名后缀参数，例如：'jpg'。
options	CreateOptions	否	创建选项，例如{title: 'testPhoto'}。

返回值：

类型	说明
Promise<string>	Promise对象，返回创建的图片和视频的uri。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('createAssetDemo');
  try {
    let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE;
    let extension: string = 'jpg';
    let options: photoAccessHelper.CreateOptions = {
      title: 'testPhoto'
    }
    let uri: string = await phAccessHelper.createAsset(photoType, extension, options);
    console.info('createAsset uri' + uri);
    console.info('createAsset successfully');
  } catch (err) {
    console.error(`createAsset failed, error: ${err.code}, ${err.message}`);
  }
}

getAlbums

getAlbums(type: AlbumType, subtype: AlbumSubtype, options: FetchOptions, callback: AsyncCallback<FetchResult<Album>>): void

根据检索选项和相册类型获取相册，使用callback方式返回结果。

获取相册前需先保证相册存在。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

参数：

参数名	类型	必填	说明
type	AlbumType	是	相册类型。
subtype	AlbumSubtype	是	相册子类型。
options	FetchOptions	是	检索选项。
callback	AsyncCallback<FetchResult<Album>>	是	callback返回获取相册的结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  // 示例代码中为获取相册名为newAlbumName的相册。
  console.info('getAlbumsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo('album_name', 'newAlbumName');
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions, async (err, fetchResult) => {
    if (err) {
      console.error(`getAlbumsCallback failed with err: ${err.code}, ${err.message}`);
      return;
    }
    if (fetchResult === undefined) {
      console.error('getAlbumsCallback fetchResult is undefined');
      return;
    }
    let album = await fetchResult.getFirstObject();
    console.info('getAlbumsCallback successfully, albumName: ' + album.albumName);
    fetchResult.close();
  });
}

getAlbums

getAlbums(type: AlbumType, subtype: AlbumSubtype, callback: AsyncCallback<FetchResult<Album>>): void

根据相册类型获取相册，使用callback方式返回结果。

获取相册前需先保证相册存在。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

参数：

参数名	类型	必填	说明
type	AlbumType	是	相册类型。
subtype	AlbumSubtype	是	相册子类型。
callback	AsyncCallback<FetchResult<Album>>	是	callback返回获取相册的结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  // 示例代码中为获取统相册VIDEO，默认已预置。
  console.info('getAlbumsDemo');
  phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO, async (err, fetchResult) => {
    if (err) {
      console.error(`getAlbumsCallback failed with err: ${err.code}, ${err.message}`);
      return;
    }
    if (fetchResult === undefined) {
      console.error('getAlbumsCallback fetchResult is undefined');
      return;
    }
    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
    console.info('getAlbumsCallback successfully, albumUri: ' + album.albumUri);
    fetchResult.close();
  });
}

getAlbums

getAlbums(type: AlbumType, subtype: AlbumSubtype, options?: FetchOptions): Promise<FetchResult<Album>>

根据检索选项和相册类型获取相册，使用Promise方式返回结果。

获取相册前需先保证相册存在。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

参数：

参数名	类型	必填	说明
type	AlbumType	是	相册类型。
subtype	AlbumSubtype	是	相册子类型。
options	FetchOptions	否	检索选项，不填时默认根据相册类型检索。

返回值：

类型	说明
Promise<FetchResult<Album>>	Promise对象，返回获取相册的结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  // 示例代码中为获取相册名为newAlbumName的相册。
  console.info('getAlbumsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo('album_name', 'newAlbumName');
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions).then( async (fetchResult) => {
    if (fetchResult === undefined) {
      console.error('getAlbumsPromise fetchResult is undefined');
      return;
    }
    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
    console.info('getAlbumsPromise successfully, albumName: ' + album.albumName);
    fetchResult.close();
  }).catch((err: BusinessError) => {
    console.error(`getAlbumsPromise failed with err: ${err.code}, ${err.message}`);
  });
}

registerChange

registerChange(uri: string, forChildUris: boolean, callback: Callback<ChangeData>) : void

注册对指定uri的监听，使用callback方式返回异步结果。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
uri	string	是	PhotoAsset的uri, Album的uri或DefaultChangeUri的值。
forChildUris	boolean	是	是否模糊监听。uri为相册uri时：forChildUris为true，能监听到相册中文件的变化。如果是false，只能监听相册本身变化；uri为photoAsset时：forChildUris为true、false没有区别；uri为DefaultChangeUri时：forChildUris必须为true，如果为false将找不到该uri，收不到任何消息。
callback	Callback<ChangeData>	是	返回要监听的ChangeData。注：uri可以注册多个不同的callback监听，unRegisterChange可以关闭该uri所有监听，也可以关闭指定callback的监听。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('registerChangeDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  if (photoAsset !== undefined) {
    console.info('photoAsset.displayName : ' + photoAsset.displayName);
  }
  let onCallback1 = (changeData: photoAccessHelper.ChangeData) => {
      console.info('onCallback1 success, changData: ' + JSON.stringify(changeData));
    //file had changed, do something.
  }
  let onCallback2 = (changeData: photoAccessHelper.ChangeData) => {
      console.info('onCallback2 success, changData: ' + JSON.stringify(changeData));
    //file had changed, do something.
  }
  // 注册onCallback1监听。
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback1);
  // 注册onCallback2监听。
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback2);

  await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [photoAsset]);
}

unRegisterChange

unRegisterChange(uri: string, callback?: Callback<ChangeData>): void

取消指定uri的监听，一个uri可以注册多个监听，存在多个callback监听时，可以取消指定注册的callback的监听；不指定callback时取消该uri的所有监听。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
uri	string	是	PhotoAsset的uri, Album的uri或DefaultChangeUri的值。
callback	Callback<ChangeData>	否	取消registerChange注册时的callback的监听，不填时，取消该uri的所有监听。注：off指定注册的callback后不会进入此回调。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('offDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  if (photoAsset !== undefined) {
    console.info('photoAsset.displayName : ' + photoAsset.displayName);
  }
  let onCallback1 = (changeData: photoAccessHelper.ChangeData) => {
    console.info('onCallback1 on');
  }
  let onCallback2 = (changeData: photoAccessHelper.ChangeData) => {
    console.info('onCallback2 on');
  }
  // 注册onCallback1监听。
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback1);
  // 注册onCallback2监听。
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback2);
  // 关闭onCallback1监听，onCallback2 继续监听。
  phAccessHelper.unRegisterChange(photoAsset.uri, onCallback1);
  await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [photoAsset]);
}

createDeleteRequest^(deprecated)

createDeleteRequest(uriList: Array<string>, callback: AsyncCallback<void>): void

创建一个弹出框来删除照片，删除的文件进入到回收站，使用callback方式返回结果。

说明：

从API version 10开始支持，从API version 11开始废弃。建议使用MediaAssetChangeRequest.deleteAssets替代。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
uriList	Array<string>	是	待删除的媒体文件uri数组，最大删除数量300。
callback	AsyncCallback<void>	是	callback返回void。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('createDeleteRequestDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    if (asset === undefined) {
      console.error('asset not exist');
      return;
    }
    phAccessHelper.createDeleteRequest([asset.uri], (err) => {
      if (err === undefined) {
        console.info('createDeleteRequest successfully');
      } else {
        console.error(`createDeleteRequest failed with error: ${err.code}, ${err.message}`);
      }
    });
  } catch (err) {
    console.error(`fetch failed, error: ${err.code}, ${err.message}`);
  }
}

createDeleteRequest^(deprecated)

createDeleteRequest(uriList: Array<string>): Promise<void>

创建一个弹出框来删除照片，删除的文件进入到回收站，使用Promise方式返回结果。

说明：

从API version 10开始支持，从API version 11开始废弃。建议使用MediaAssetChangeRequest.deleteAssets替代。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
uriList	Array<string>	是	待删除的媒体文件uri数组，最大删除数量300。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('createDeleteRequestDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    if (asset === undefined) {
      console.error('asset not exist');
      return;
    }
    await phAccessHelper.createDeleteRequest([asset.uri]);
    console.info('createDeleteRequest successfully');
  } catch (err) {
    console.error(`createDeleteRequest failed with error: ${err.code}, ${err.message}`);
  }
}

applyChanges¹¹⁺

applyChanges(mediaChangeRequest: MediaChangeRequest): Promise<void>

提交媒体变更请求，使用Promise方式返回结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

在提交创建资产的变更请求时，用安全控件的方式调用该接口来创建媒体资源，不需要申请'ohos.permission.WRITE_IMAGEVIDEO'权限，详情请参考开发指南。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
mediaChangeRequest	MediaChangeRequest	是	媒体变更请求，支持资产变更请求和相册变更请求。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

该接口依赖于MediaChangeRequest对象，详细代码示例请参见MediaAssetChangeRequest和MediaAlbumChangeRequest中的接口示例。

release

release(callback: AsyncCallback<void>): void

释放PhotoAccessHelper实例，使用callback方式返回结果。当后续不需要使用PhotoAccessHelper实例中的方法时调用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调表示成功还是失败。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('releaseDemo');
  phAccessHelper.release((err) => {
    if (err !== undefined) {
      console.error(`release failed. error: ${err.code}, ${err.message}`);
    } else {
      console.info('release ok.');
    }
  });
}

release

release(): Promise<void>

释放PhotoAccessHelper实例，使用Promise方式返回结果。当后续不需要使用PhotoAccessHelper 实例中的方法时调用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('releaseDemo');
  try {
    await phAccessHelper.release();
    console.info('release ok.');
  } catch (err) {
    console.error(`release failed. error: ${err.code}, ${err.message}`);
  }
}

showAssetsCreationDialog¹²⁺

showAssetsCreationDialog(srcFileUris: Array<string>, photoCreationConfigs: Array<PhotoCreationConfig>): Promise<Array<string>>

调用接口拉起保存确认弹窗。用户同意保存后，返回已创建并授予保存权限的uri列表，该列表永久生效，应用可使用该uri写入图片/视频。如果用户拒绝保存，将返回空列表。弹框需要显示应用名称，无法直接获取应用名称，依赖于配置项的label和icon，因此调用此接口时请确保module.json5文件中的abilities标签中配置了label和icon项。

说明： 当传入uri为沙箱路径时，可正常保存图片/视频，但无界面预览。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
srcFileUris	Array<string>	是	需保存到媒体库中的图片/视频文件对应的媒体库uri。注意： - 仅支持处理图片、视频uri。 - 不支持手动拼接的uri，需调用接口获取，获取方式参考媒体文件uri获取方式。
photoCreationConfigs	Array<PhotoCreationConfig>	是	保存图片/视频到媒体库的配置，包括保存的文件名等，与srcFileUris保持一一对应。

返回值：

类型	说明
Promise<Array<string>>	Promise对象，返回给应用的媒体库文件uri列表。Uri已对应用授权，支持应用写入数据。如果生成uri异常，则返回批量创建错误码。返回-3006表示不允许出现非法字符；返回-2004表示图片类型和后缀不符；返回-203表示文件操作异常。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

async function example() {
  console.info('ShowAssetsCreationDialogDemo.');

  try {
    // 获取需要保存到媒体库的位于应用沙箱的图片/视频uri。
    let srcFileUris: Array<string> = [
      'file://fileUriDemo1' // 实际场景请使用真实的uri。
    ];
    let photoCreationConfigs: Array<photoAccessHelper.PhotoCreationConfig> = [
      {
        title: 'test2', // 可选。
        fileNameExtension: 'jpg',
        photoType: photoAccessHelper.PhotoType.IMAGE,
        subtype: photoAccessHelper.PhotoSubtype.DEFAULT, // 可选。
      }
    ];
    let desFileUris: Array<string> = await phAccessHelper.showAssetsCreationDialog(srcFileUris, photoCreationConfigs);
    console.info('showAssetsCreationDialog success, data is ' + desFileUris);
  } catch (err) {
    console.error('showAssetsCreationDialog failed, errCode is ' + err.code + ', errMsg is ' + err.message);
  }
}

createAssetWithShortTermPermission¹²⁺

createAssetWithShortTermPermission(photoCreationConfig: PhotoCreationConfig): Promise<string>

接口提供给应用调用，支持首次调用后拉起保存确认弹框。在用户同意保存后返回已创建并授予保存权限的uri，支持应用使用uri写入图片/视频；在用户"同意"后的5min之内，同一个应用再次调用接口，支持无需弹框确认自动返回已授权的uri给应用，支持应用保存图片/视频。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限： ohos.permission.SHORT_TERM_WRITE_IMAGEVIDEO

参数：

参数名	类型	必填	说明
photoCreationConfig	PhotoCreationConfig;	是	保存图片/视频到媒体库的配置，包括保存的文件名等。

返回值：

类型	说明
Promise<string>	Promise对象，返回给应用的媒体库文件uri。Uri已对应用授权，支持应用写入数据。如果生成uri异常，则返回批量创建错误码。返回-3006表不允许出现非法字符；返回-2004表示图片类型和后缀不符；返回-203表示文件操作异常。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error

示例：

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

async function example() {
    console.info('createAssetWithShortTermPermissionDemo.');
    
    try {
        let photoCreationConfig: photoAccessHelper.PhotoCreationConfig = {
            title: '123456', 
            fileNameExtension: 'jpg',
            photoType: photoAccessHelper.PhotoType.IMAGE,
            subtype: photoAccessHelper.PhotoSubtype.DEFAULT, 
        };

        let resultUri: string = await phAccessHelper.createAssetWithShortTermPermission(photoCreationConfig);
        let resultFile: fileIo.File = fileIo.openSync(resultUri, fileIo.OpenMode.READ_WRITE);
        // 实际场景请使用真实的uri和文件大小。
        let srcFile:  fileIo.File = fileIo.openSync("file://test.jpg", fileIo.OpenMode.READ_ONLY);
        let bufSize: number = 2000000;
        let readSize: number = 0;
        let buf = new ArrayBuffer(bufSize);
        let readLen = fileIo.readSync(srcFile.fd, buf, {
            offset: readSize,
            length: bufSize
        });
        if (readLen > 0) {
            readSize += readLen;
            fileIo.writeSync(resultFile.fd, buf, { length: readLen });
        }
        fileIo.closeSync(srcFile);
        fileIo.closeSync(resultFile);
    } catch (err) {
        console.error('createAssetWithShortTermPermission failed, errCode is ' + err.code + ', errMsg is ' + err.message);
    }
    
}

requestPhotoUrisReadPermission¹⁴⁺

requestPhotoUrisReadPermission(srcFileUris: Array<string>): Promise<Array<string>>

调用接口给未授权的uri进行授权，返回已创建并授予保存权限的uri列表。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
srcFileUris	Array<string>	是	需进行授权的图片/视频文件对应的媒体库uri。注意：仅支持处理图片、视频uri。

返回值：

类型	说明
Promise<Array<string>>	Promise对象，返回已授权的uri列表。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

async function example() {
  console.info('requestPhotoUrisReadPermissionDemo.');

  try {
    let phAccessHelper: photoAccessHelper.PhotoAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
    // 获取需要进行授权的图片/视频uri。
    let srcFileUris: Array<string> = [
      'file://fileUriDemo1' // 实际场景请使用真实的uri。
    ];
    let desFileUris: Array<string> = await phAccessHelper.requestPhotoUrisReadPermission(srcFileUris);
    console.info('requestPhotoUrisReadPermission success, data is ' + desFileUris);
  } catch (err) {
    console.error('requestPhotoUrisReadPermission failed, errCode is ' + err.code + ', errMsg is ' + err.message);
  }
}

getSupportedPhotoFormats¹⁸⁺

getSupportedPhotoFormats(photoType: PhotoType): Promise<Array<string>>

接口提供给应用调用，获取媒体库支持的图片或者视频后缀列表。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
photoType	PhotoType	是	媒体文件类型。

返回值：

类型	说明
Promise<Array<string>>	Promise对象，返回支持的图片或者视频后缀列表。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;
14000011	Internal system error. It is recommended to retry and check the logs.

示例：

import photoAccessHelper from '@ohos.file.photoAccessHelper';

async function example(photoTypeNumber: number){
  console.info('getSupportedPhotoFormatsDemo.');

  try {
    if (photoTypeNumber !== 1 && photoTypeNumber !== 2) {
      outputText = 'Does not support querying formats other than images or videos';
      return;
    }
    outputText = 'The supported types are:\n';
    let imageFormat  = await phAccessHelper.getSupportedPhotoFormats(photoTypeNumber);
    let result = "";
    for (let i = 0; i < imageFormat.length; i++) {
      result += imageFormat[i];
      if (i !== imageFormat.length - 1) {
        result += ', ';
      }
    }
    outputText += result;
    console.info('getSupportedPhotoFormats success, data is ' + outputText);
  } catch (error) {
    console.error('getSupportedPhotoFormats failed, errCode is', error);
  }
}

PhotoAsset

提供封装文件属性的方法。

属性

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	可读	可写	说明
uri	string	是	否	媒体文件资源uri（如：file://media/Photo/1/IMG_datetime_0001/displayName.jpg），详情参见用户文件uri介绍中的媒体文件uri 原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
photoType	PhotoType	是	否	媒体文件类型。
displayName	string	是	否	显示文件名，包含后缀名。

get

get(member: string): MemberType

获取PhotoAsset成员参数。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
member	string	是	成员参数名称，在get时，除了'uri'、'media_type'、'subtype'和'display_name'四个属性之外，其他的属性都需要在fetchColumns中填入需要get的PhotoKeys，例如：get title属性fetchColumns: ['title']。

返回值：

类型	说明
MemberType	获取PhotoAsset成员参数的值。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000014	Member is not a valid PhotoKey.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('photoAssetGetDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: ['title'],
      predicates: predicates
    };
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let title: photoAccessHelper.PhotoKeys = photoAccessHelper.PhotoKeys.TITLE;
    let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title.toString());
    console.info('photoAsset Get photoAssetTitle = ', photoAssetTitle);
  } catch (err) {
    console.error(`release failed. error: ${err.code}, ${err.message}`);
  }
}

set

set(member: string, value: string): void

设置PhotoAsset成员参数。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
member	string	是	成员参数名称例如：PhotoKeys.TITLE。
value	string	是	设置成员参数名称，只能修改PhotoKeys.TITLE的值。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000014	Member is not a valid PhotoKey.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('photoAssetSetDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: ['title'],
      predicates: predicates
    };
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let title: string = photoAccessHelper.PhotoKeys.TITLE.toString();
    photoAsset.set(title, 'newTitle');
  } catch (err) {
    console.error(`release failed. error: ${err.code}, ${err.message}`);
  }
}

commitModify

commitModify(callback: AsyncCallback<void>): void

修改文件的元数据，使用callback方式返回异步结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	callback返回void。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000001	Invalid display name.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('commitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: ['title'],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  let title: string = photoAccessHelper.PhotoKeys.TITLE.toString();
  let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title);
  console.info('photoAsset get photoAssetTitle = ', photoAssetTitle);
  photoAsset.set(title, 'newTitle2');
  photoAsset.commitModify((err) => {
    if (err === undefined) {
      let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title);
      console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle);
    } else {
      console.error(`commitModify failed, error: ${err.code}, ${err.message}`);
    }
  });
}

commitModify

commitModify(): Promise<void>

修改文件的元数据，使用promise方式返回异步结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000001	Invalid display name.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('commitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: ['title'],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  let title: string = photoAccessHelper.PhotoKeys.TITLE.toString();
  let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title);
  console.info('photoAsset get photoAssetTitle = ', photoAssetTitle);
  photoAsset.set(title, 'newTitle3');
  try {
    await photoAsset.commitModify();
    let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title);
    console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle);
  } catch (err) {
    console.error(`release failed. error: ${err.code}, ${err.message}`);
  }
}

getReadOnlyFd^(deprecated)

getReadOnlyFd(callback: AsyncCallback<number>): void

以只读方式打开当前文件，使用callback方式返回异步结果。

说明：

从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。

注意：返回的文件描述符在使用完毕后需要调用close进行释放。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<number>	是	callback返回文件描述符。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('getReadOnlyFdDemo');
  // 需要保证设备中存在可读取图片视频文件。
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
  photoAsset.getReadOnlyFd((err, fd) => {
    if (fd !== undefined) {
      console.info('File fd' + fd);
      photoAsset.close(fd);
    } else {
      console.error(`getReadOnlyFd err: ${err.code}, ${err.message}`);
    }
  });
}

getReadOnlyFd^(deprecated)

getReadOnlyFd(): Promise<number>

以只读方式打开当前文件，使用promise方式返回异步结果。

说明：

从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。

注意：返回的文件描述符在使用完毕后需要调用close进行释放。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Promise<number>	Promise对象，返回文件描述符。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

async function example() {
  console.info('getReadOnlyFdDemo');
  try {
    // 需要保证设备中存在可读取图片视频文件。
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOptions: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
    let fd: number = await photoAsset.getReadOnlyFd();
    if (fd !== undefined) {
      console.info('File fd' + fd);
      photoAsset.close(fd);
    } else {
      console.error('getReadOnlyFd fail');
    }
  } catch (err) {
    console.error(`getReadOnlyFd demo err: ${err.code}, ${err.message}`);
  }
}

close^(deprecated)

close(fd: number, callback: AsyncCallback<void>): void

关闭当前文件，使用callback方式返回异步结果。

说明：

从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。对应的close接口一并废弃。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
fd	number	是	文件描述符。
callback	AsyncCallback<void>	是	callback返回void。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('closeDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let fd: number = await photoAsset.open('rw');
    console.info('file fd', fd);
    photoAsset.close(fd, (err) => {
      if (err === undefined) {
        console.info('asset close succeed.');
      } else {
        console.error(`close failed, error: ${err.code}, ${err.message}`);
      }
    });
  } catch (err) {
    console.error(`close failed, error: ${err.code}, ${err.message}`);
  }
}

close^(deprecated)

close(fd: number): Promise<void>

关闭当前文件，使用promise方式返回异步结果。

说明：

从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。对应的close接口一并废弃。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
fd	number	是	文件描述符。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('closeDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let fd = await asset.open('rw');
    console.info('file fd', fd);
    await asset.close(fd);
    console.info('asset close succeed.');
  } catch (err) {
    console.error(`close failed, error: ${err.code}, ${err.message}`);
  }
}

getThumbnail

getThumbnail(callback: AsyncCallback<image.PixelMap>): void

获取文件的缩略图，使用callback方式返回异步结果。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<image.PixelMap>	是	callback返回缩略图的PixelMap。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getThumbnailDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  console.info('asset displayName = ', asset.displayName);
  asset.getThumbnail((err, pixelMap) => {
    if (err === undefined) {
      console.info('getThumbnail successful ' + pixelMap);
    } else {
      console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`);
    }
  });
}

getThumbnail

getThumbnail(size: image.Size, callback: AsyncCallback<image.PixelMap>): void

获取文件的缩略图，传入缩略图尺寸，使用callback方式返回异步结果。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
size	image.Size	是	缩略图尺寸。
callback	AsyncCallback<image.PixelMap>	是	callback返回缩略图的PixelMap。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

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

async function example() {
  console.info('getThumbnailDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let size: image.Size = { width: 720, height: 720 };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let asset = await fetchResult.getFirstObject();
  console.info('asset displayName = ', asset.displayName);
  asset.getThumbnail(size, (err, pixelMap) => {
    if (err === undefined) {
      console.info('getThumbnail successful ' + pixelMap);
    } else {
      console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`);
    }
  });
}

getThumbnail

getThumbnail(size?: image.Size): Promise<image.PixelMap>

获取文件的缩略图，传入缩略图尺寸，使用promise方式返回异步结果。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
size	image.Size	否	缩略图尺寸。

返回值：

类型	说明
Promise<image.PixelMap>	Promise对象，返回缩略图的PixelMap。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  console.info('getThumbnailDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let size: image.Size = { width: 720, height: 720 };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let asset = await fetchResult.getFirstObject();
  console.info('asset displayName = ', asset.displayName);
  asset.getThumbnail(size).then((pixelMap) => {
    console.info('getThumbnail successful ' + pixelMap);
  }).catch((err: BusinessError) => {
    console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`);
  });
}

clone¹⁴⁺

clone(title: string): Promise<PhotoAsset>

将一个资产进行克隆，支持设置文件名，不支持修改文件类型。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
title	string	是	克隆后资产的标题。参数规格为： - 不应包含扩展名。 - 文件名字符串长度为1~255（资产文件名为标题+扩展名）。 - 不允许出现非法字符，包括：. \ / : * ? " ' ` < > \| { } [ ]

返回值：

类型	说明
Promise<PhotoAsset>	Promise对象，返回PhotoAsset。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error. It is recommended to retry and check the logs.Possible causes: 1. Database corrupted; 2. The file system is abnormal; 3. The IPC request timed out.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { systemDateTime } from '@kit.BasicServicesKit';

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let title: string = systemDateTime.getTime().toString();
    let newAsset: photoAccessHelper.PhotoAsset = await photoAsset.clone(title);
    console.info('get new asset successfully');
  } catch (error) {
    console.error(`failed to get new asset. message =  ${error.code}, ${error.message}`);
  }
}

PhotoViewPicker

图库选择器对象，用来支撑选择图片/视频等用户场景。在使用前，需要先创建PhotoViewPicker实例。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

示例：

let photoPicker = new photoAccessHelper.PhotoViewPicker();

select

select(option?: PhotoSelectOptions) : Promise<PhotoSelectResult>

通过选择模式拉起photoPicker界面，用户可以选择一个或多个图片/视频。接口采用promise异步返回形式，传入可选参数PhotoSelectOptions对象，返回PhotoSelectResult对象。

注意：此接口返回的PhotoSelectResult对象中的photoUris具有永久授权，可通过调用photoAccessHelper.getAssets接口去使用，具体使用方式参见用户文件uri介绍中的媒体文件uri的使用方式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
option	PhotoSelectOptions	否	photoPicker选择选项，若无此参数，则默认选择媒体文件类型为图片和视频类型，默认选择媒体文件数量的最大值为50。

返回值：

类型	说明
Promise<PhotoSelectResult>	Promise对象。返回photoPicker选择后的结果集

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900042	Unknown error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
async function example01() {
  try {
    let PhotoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
    PhotoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
    PhotoSelectOptions.maxSelectNumber = 5;
    let photoPicker = new photoAccessHelper.PhotoViewPicker();
    photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => {
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
    }).catch((err: BusinessError) => {
      console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`);
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`);
  }
}

select

select(option: PhotoSelectOptions, callback: AsyncCallback<PhotoSelectResult>) : void

通过选择模式拉起photoPicker界面，用户可以选择一个或多个图片/视频。接口采用callback异步返回形式，传入参数PhotoSelectOptions对象，返回PhotoSelectResult对象。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
option	PhotoSelectOptions	是	photoPicker选择选项。
callback	AsyncCallback<PhotoSelectResult>	是	callback 返回photoPicker选择后的结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900042	Unknown error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
async function example02() {
  try {
    let PhotoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
    PhotoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
    PhotoSelectOptions.maxSelectNumber = 5;
    let photoPicker = new photoAccessHelper.PhotoViewPicker();
    photoPicker.select(PhotoSelectOptions, (err: BusinessError, PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => {
      if (err) {
        console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`);
        return;
      }
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`);
  }
}

select

select(callback: AsyncCallback<PhotoSelectResult>) : void

通过选择模式拉起photoPicker界面，用户可以选择一个或多个图片/视频。接口采用callback异步返回形式，返回PhotoSelectResult对象。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<PhotoSelectResult>	是	callback 返回photoPicker选择后的结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900042	Unknown error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
async function example03() {
  try {
    let photoPicker = new photoAccessHelper.PhotoViewPicker();
    photoPicker.select((err: BusinessError, PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => {
      if (err) {
        console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`);
        return;
      }
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`);
  }
}

FetchResult

文件检索结果集。

getCount

getCount(): number

获取文件检索结果中的文件总数。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
number	检索到的文件总数。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getCountDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let fetchCount = fetchResult.getCount();
  console.info('fetchCount = ', fetchCount);
}

isAfterLast

isAfterLast(): boolean

检查结果集是否指向最后一行。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
boolean	当读到最后一条记录后，后续没有记录返回true，否则返回false。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let fetchCount = fetchResult.getCount();
  console.info('count:' + fetchCount);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getLastObject();
  if (fetchResult.isAfterLast()) {
    console.info('photoAsset isAfterLast displayName = ', photoAsset.displayName);
  } else {
    console.info('photoAsset not isAfterLast.');
  }
}

close

close(): void

释放FetchResult实例并使其失效。无法调用其他方法。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('fetchResultCloseDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    fetchResult.close();
    console.info('close succeed.');
  } catch (err) {
    console.error(`close fail. error: ${err.code}, ${err.message}`);
  }
}

getFirstObject

getFirstObject(callback: AsyncCallback<T>): void

获取文件检索结果中的第一个文件资产。此方法使用callback形式返回结果。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<T>	是	异步获取结果集中的第一个完成后的回调。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getFirstObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  fetchResult.getFirstObject((err, photoAsset) => {
    if (photoAsset !== undefined) {
      console.info('photoAsset displayName: ', photoAsset.displayName);
    } else {
      console.error(`photoAsset failed with err:${err.code}, ${err.message}`);
    }
  });
}

getFirstObject

getFirstObject(): Promise<T>

获取文件检索结果中的第一个文件资产。此方法使用promise方式来异步返回。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Promise<T>	Promise对象，返回结果集中第一个对象。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getFirstObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  console.info('photoAsset displayName: ', photoAsset.displayName);
}

getNextObject

getNextObject(callback: AsyncCallback<T>): void

获取文件检索结果中的下一个文件资产。此方法使用callback形式返回结果。在调用此方法之前，必须使用isAfterLast()来检查当前位置是否为最后一行。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<T>	是	异步返回结果集中下一个之后的回调。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getNextObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  await fetchResult.getFirstObject();
  if (!fetchResult.isAfterLast()) {
    fetchResult.getNextObject((err, photoAsset) => {
      if (photoAsset !== undefined) {
        console.info('photoAsset displayName: ', photoAsset.displayName);
      } else {
        console.error(`photoAsset failed with err: ${err.code}, ${err.message}`);
      }
    });
  }
}

getNextObject

getNextObject(): Promise<T>

获取文件检索结果中的下一个文件资产。此方法使用promise方式来异步返回。在调用此方法之前，必须使用isAfterLast()来检查当前位置是否为最后一行。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Promise<T>	Promise对象，返回结果集中下一个对象。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getNextObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  await fetchResult.getFirstObject();
  if (!fetchResult.isAfterLast()) {
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getNextObject();
    console.info('photoAsset displayName: ', photoAsset.displayName);
  }
}

getLastObject

getLastObject(callback: AsyncCallback<T>): void

获取文件检索结果中的最后一个文件资产。此方法使用callback回调来返回。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<T>	是	异步返回结果集中最后一个的回调。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getLastObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  fetchResult.getLastObject((err, photoAsset) => {
    if (photoAsset !== undefined) {
      console.info('photoAsset displayName: ', photoAsset.displayName);
    } else {
      console.error(`photoAsset failed with err: ${err.code}, ${err.message}`);
    }
  });
}

getLastObject

getLastObject(): Promise<T>

获取文件检索结果中的最后一个文件资产。此方法使用Promise方式来返回。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Promise<T>	Promise对象，返回结果集中最后一个对象。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getLastObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getLastObject();
  console.info('photoAsset displayName: ', photoAsset.displayName);
}

getObjectByPosition

getObjectByPosition(index: number, callback: AsyncCallback<T>): void

获取文件检索结果中具有指定索引的文件资产。此方法使用callback来返回。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
index	number	是	要获取的文件的索引，从0开始。
callback	AsyncCallback<T>	是	异步返回指定索引的文件资产的回调。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getObjectByPositionDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  fetchResult.getObjectByPosition(0, (err, photoAsset) => {
    if (photoAsset !== undefined) {
      console.info('photoAsset displayName: ', photoAsset.displayName);
    } else {
      console.error(`photoAsset failed with err: ${err.code}, ${err.message}`);
    }
  });
}

getObjectByPosition

getObjectByPosition(index: number): Promise<T>

获取文件检索结果中具有指定索引的文件资产。此方法使用Promise形式返回文件Asset。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
index	number	是	要获取的文件的索引，从0开始。

返回值：

类型	说明
Promise<T>	Promise对象，返回结果集中指定索引的一个对象。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getObjectByPositionDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getObjectByPosition(0);
  console.info('photoAsset displayName: ', photoAsset.displayName);
}

getAllObjects

getAllObjects(callback: AsyncCallback<Array<T>>): void

获取文件检索结果中的所有文件资产。此方法使用callback形式返回结果。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<T>>	是	异步获取结果集中的所有文件资产完成后的回调。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getAllObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  fetchResult.getAllObjects((err, photoAssetList) => {
    if (photoAssetList !== undefined) {
      console.info('photoAssetList length: ', photoAssetList.length);
    } else {
      console.error(`photoAssetList failed with err:${err.code}, ${err.message}`);
    }
  });
}

getAllObjects

getAllObjects(): Promise<Array<T>>

获取文件检索结果中的所有文件资产。此方法使用promise方式来异步返回。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Promise<Array<T>>	Promise对象，返回结果集中所有文件资产数组。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('getAllObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let photoAssetList: Array<photoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects();
  console.info('photoAssetList length: ', photoAssetList.length);
}

Album

实体相册

属性

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	可读	可写	说明
albumType	AlbumType	是	否	相册类型。
albumSubtype	AlbumSubtype	是	否	相册子类型。
albumName	string	是	用户相册可写，预置相册不可写	相册名称。
albumUri	string	是	否	相册Uri。
count	number	是	否	相册中文件数量。
coverUri	string	是	否	封面文件Uri。
imageCount¹¹⁺	number	是	否	相册中图片数量。
videoCount¹¹⁺	number	是	否	相册中视频数量。

getAssets

getAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<PhotoAsset>>): void

获取相册中的文件。该方法使用callback形式来返回文件。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
options	FetchOptions	是	检索选项。
callback	AsyncCallback<FetchResult<PhotoAsset>>	是	callback返回图片和视频数据结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('albumGetAssetsDemoCallback');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
  let album: photoAccessHelper.Album = await albumList.getFirstObject();
  album.getAssets(fetchOption, (err, albumFetchResult) => {
    if (albumFetchResult !== undefined) {
      console.info('album getAssets successfully, getCount: ' + albumFetchResult.getCount());
    } else {
      console.error(`album getAssets failed with error: ${err.code}, ${err.message}`);
    }
  });
}

getAssets

getAssets(options: FetchOptions): Promise<FetchResult<PhotoAsset>>

获取相册中的文件。该方法使用Promise来返回文件。

需要权限：ohos.permission.READ_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
options	FetchOptions	是	检索选项。

返回值：

类型	说明
Promise<FetchResult<PhotoAsset>>	Promise对象，返回图片和视频数据结果集。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  console.info('albumGetAssetsDemoPromise');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
  let album: photoAccessHelper.Album = await albumList.getFirstObject();
  album.getAssets(fetchOption).then((albumFetchResult) => {
    console.info('album getAssets successfully, getCount: ' + albumFetchResult.getCount());
  }).catch((err: BusinessError) => {
    console.error(`album getAssets failed with error: ${err.code}, ${err.message}`);
  });
}

commitModify

commitModify(callback: AsyncCallback<void>): void

更新相册属性修改到数据库中。该方法使用callback形式来返回结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	callback返回void。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('albumCommitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
  let album: photoAccessHelper.Album = await albumList.getFirstObject();
  album.albumName = 'hello';
  album.commitModify((err) => {
    if (err !== undefined) {
      console.error(`commitModify failed with error: ${err.code}, ${err.message}`);
    } else {
      console.info('commitModify successfully');
    }
  });
}

commitModify

commitModify(): Promise<void>

更新相册属性修改到数据库中。该方法使用Promise来返回结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  console.info('albumCommitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
  let album: photoAccessHelper.Album = await albumList.getFirstObject();
  album.albumName = 'hello';
  album.commitModify().then(() => {
    console.info('commitModify successfully');
  }).catch((err: BusinessError) => {
    console.error(`commitModify failed with error: ${err.code}, ${err.message}`);
  });
}

addAssets^(deprecated)

addAssets(assets: Array<PhotoAsset>, callback: AsyncCallback<void>): void

往相册中添加图片或者视频，需要先预置相册和文件资源。该方法使用callback形式来返回结果。

说明：

从API version 10开始支持，从API version 11开始废弃。建议使用MediaAlbumChangeRequest.addAssets替代。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
assets	Array<PhotoAsset>	是	待添加到相册中的图片或视频数组。
callback	AsyncCallback<void>	是	callback返回void。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  try {
    console.info('addAssetsDemoCallback');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    album.addAssets([asset], (err) => {
      if (err === undefined) {
        console.info('album addAssets successfully');
      } else {
        console.error(`album addAssets failed with error: ${err.code}, ${err.message}`);
      }
    });
  } catch (err) {
    console.error(`addAssetsDemoCallback failed with error: ${err.code}, ${err.message}`);
  }
}

addAssets^(deprecated)

addAssets(assets: Array<PhotoAsset>): Promise<void>

往相册中添加图片或者视频，需要先预置相册和文件资源。该方法使用Promise来返回结果。

说明：

从API version 10开始支持，从API version 11开始废弃。建议使用MediaAlbumChangeRequest.addAssets替代。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
assets	Array<PhotoAsset>	是	待添加到相册中的图片或视频数组。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  try {
    console.info('addAssetsDemoPromise');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    album.addAssets([asset]).then(() => {
      console.info('album addAssets successfully');
    }).catch((err: BusinessError) => {
      console.error(`album addAssets failed with error: ${err.code}, ${err.message}`);
    });
  } catch (err) {
    console.error(`addAssetsDemoPromise failed with error: ${err.code}, ${err.message}`);
  }
}

removeAssets^(deprecated)

removeAssets(assets: Array<PhotoAsset>, callback: AsyncCallback<void>): void

从相册中移除图片或者视频，需要先预置相册和文件资源。该方法使用callback形式来返回结果。

说明：

从API version 10开始支持，从API version 11开始废弃。建议使用MediaAlbumChangeRequest.removeAssets替代。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
assets	Array<PhotoAsset>	是	相册中待移除的图片或视频数组。
callback	AsyncCallback<void>	是	callback返回void。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  try {
    console.info('removeAssetsDemoCallback');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOption);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    album.removeAssets([asset], (err) => {
      if (err === undefined) {
        console.info('album removeAssets successfully');
      } else {
        console.error(`album removeAssets failed with error: ${err.code}, ${err.message}`);
      }
    });
  } catch (err) {
    console.error(`removeAssetsDemoCallback failed with error: ${err.code}, ${err.message}`);
  }
}

removeAssets^(deprecated)

removeAssets(assets: Array<PhotoAsset>): Promise<void>

从相册中移除图片或者视频，需要先预置相册和文件资源。该方法使用Promise来返回结果。

说明：

从API version 10开始支持，从API version 11开始废弃。建议使用MediaAlbumChangeRequest.removeAssets替代。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
assets	Array<PhotoAsset>	是	相册中待移除的图片或视频数组。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900012	Permission denied.
13900020	Invalid argument.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  try {
    console.info('removeAssetsDemoPromise');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOption);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    album.removeAssets([asset]).then(() => {
      console.info('album removeAssets successfully');
    }).catch((err: BusinessError) => {
      console.error(`album removeAssets failed with error: ${err.code}, ${err.message}`);
    });
  } catch (err) {
    console.error(`removeAssetsDemoPromise failed with error: ${err.code}, ${err.message}`);
  }
}

MediaAssetChangeRequest¹¹⁺

资产变更请求。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

constructor¹¹⁺

constructor(asset: PhotoAsset)

构造函数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
asset	PhotoAsset	是	需要变更的资产。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('MediaAssetChangeRequest constructorDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
  let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
}

createImageAssetRequest¹¹⁺

static createImageAssetRequest(context: Context, fileUri: string): MediaAssetChangeRequest

创建图片资产变更请求。

通过fileUri指定待创建资产的数据来源，可参考FileUri。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
fileUri	string	是	图片资产的数据来源，在应用沙箱下的uri。示例fileUri为：'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg'。

返回值：

类型	说明
MediaAssetChangeRequest	返回创建资产的变更请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900002	No such file.
14000011	System inner fail.

示例：

async function example() {
  console.info('createImageAssetRequestDemo');
  try {
    // 需要确保fileUri对应的资源存在。
    let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg';
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createImageAssetRequest(context, fileUri);
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('apply createImageAssetRequest successfully');
  } catch (err) {
    console.error(`createImageAssetRequestDemo failed with error: ${err.code}, ${err.message}`);
  }
}

createVideoAssetRequest¹¹⁺

static createVideoAssetRequest(context: Context, fileUri: string): MediaAssetChangeRequest

创建视频资产变更请求。

通过fileUri指定待创建资产的数据来源，可参考FileUri。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
fileUri	string	是	视频资产的数据来源，在应用沙箱下的uri。示例fileUri为：'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.mp4'。

返回值：

类型	说明
MediaAssetChangeRequest	返回创建资产的变更请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900002	No such file.
14000011	System inner fail.

示例：

async function example() {
  console.info('createVideoAssetRequestDemo');
  try {
    // 需要确保fileUri对应的资源存在。
    let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.mp4';
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createVideoAssetRequest(context, fileUri);
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('apply createVideoAssetRequest successfully');
  } catch (err) {
    console.error(`createVideoAssetRequestDemo failed with error: ${err.code}, ${err.message}`);
  }
}

createAssetRequest¹¹⁺

static createAssetRequest(context: Context, photoType: PhotoType, extension: string, options?: CreateOptions): MediaAssetChangeRequest

指定待创建的文件类型和扩展名，创建资产变更请求。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
photoType	PhotoType	是	待创建的文件类型，IMAGE或者VIDEO类型。
extension	string	是	文件扩展名，例如：'jpg'。
options	CreateOptions	否	创建选项，例如：{title: 'testPhoto'}。

返回值：

类型	说明
MediaAssetChangeRequest	返回创建资产的变更请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

async function example() {
  console.info('createAssetRequestDemo');
  try {
    let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE;
    let extension: string = 'jpg';
    let options: photoAccessHelper.CreateOptions = {
      title: 'testPhoto'
    }
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension, options);
    // 需要确保fileUri对应的资源存在。
    let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg';
    assetChangeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, fileUri);
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('apply createAssetRequest successfully');
  } catch (err) {
    console.error(`createAssetRequestDemo failed with error: ${err.code}, ${err.message}`);
  }
}

deleteAssets¹¹⁺

static deleteAssets(context: Context, assets: Array<PhotoAsset>): Promise<void>

删除媒体文件，删除的文件进入到回收站，使用Promise方式返回结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
assets	Array<PhotoAsset>	是	待删除的媒体文件数组，最大删除数量300。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('deleteAssetsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let photoAssetList: Array<photoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects();
    await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, photoAssetList);
    console.info('deleteAssets successfully');
  } catch (err) {
    console.error(`deleteAssetsDemo failed with error: ${err.code}, ${err.message}`);
  }
}

deleteAssets¹¹⁺

static deleteAssets(context: Context, uriList: Array<string>): Promise<void>

删除媒体文件，删除的文件进入到回收站，使用Promise方式返回结果。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
uriList	Array<string>	是	待删除的媒体文件uri数组，最大删除数量300。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000002	Invalid asset uri.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('deleteAssetsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [asset.uri]);
    console.info('deleteAssets successfully');
  } catch (err) {
    console.error(`deleteAssetsDemo failed with error: ${err.code}, ${err.message}`);
  }
}

getAsset¹¹⁺

getAsset(): PhotoAsset

获取当前资产变更请求中的资产。

注意：对于创建资产的变更请求，在调用applyChanges提交生效之前，该接口返回null。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
PhotoAsset	返回当前资产变更请求中的资产。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14000011	System inner fail.

示例：

async function example() {
  console.info('getAssetDemo');
  try {
    // 需要确保fileUri对应的资源存在。
    let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg';
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createImageAssetRequest(context, fileUri);
    await phAccessHelper.applyChanges(assetChangeRequest);
    let asset: photoAccessHelper.PhotoAsset = assetChangeRequest.getAsset();
    console.info('create asset successfully with uri = ' + asset.uri);
  } catch (err) {
    console.error(`getAssetDemo failed with error: ${err.code}, ${err.message}`);
  }
}

setTitle¹¹⁺

setTitle(title: string): void

修改媒体资产的标题。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
title	string	是	待修改的资产标题。

title参数规格为：

不应包含扩展名。
文件名字符串长度为1~255。
不允许出现非法字符，包括：
. \ / : * ? " ' ` < > | { } [ ]

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  console.info('setTitleDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let asset = await fetchResult.getFirstObject();
  let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset);
  let newTitle: string = 'newTitle';
  assetChangeRequest.setTitle(newTitle);
  phAccessHelper.applyChanges(assetChangeRequest).then(() => {
    console.info('apply setTitle successfully');
  }).catch((err: BusinessError) => {
    console.error(`apply setTitle failed with error: ${err.code}, ${err.message}`);
  });
}

getWriteCacheHandler¹¹⁺

getWriteCacheHandler(): Promise<number>

获取临时文件写句柄。

注意：对于同一个资产变更请求，不支持在成功获取临时文件写句柄后，重复调用该接口。

需要权限：ohos.permission.WRITE_IMAGEVIDEO

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Promise<number>	Promise对象，返回临时文件写句柄。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14000011	System inner fail.
14000016	Operation Not Support.

示例：

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

async function example() {
  console.info('getWriteCacheHandlerDemo');
  try {
    let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.VIDEO;
    let extension: string = 'mp4';
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension);
    let fd: number = await assetChangeRequest.getWriteCacheHandler();
    console.info('getWriteCacheHandler successfully');
    // write date into fd..
    await fileIo.close(fd);
    await phAccessHelper.applyChanges(assetChangeRequest);
  } catch (err) {
    console.error(`getWriteCacheHandlerDemo failed with error: ${err.code}, ${err.message}`);
  }
}

addResource¹¹⁺

addResource(type: ResourceType, fileUri: string): void

通过fileUri从应用沙箱添加资源。

注意：对于同一个资产变更请求，不支持在成功添加资源后，重复调用该接口。对于动态照片，可调用两次该接口分别添加图片和视频资源。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
type	ResourceType	是	待添加资源的类型。
fileUri	string	是	待添加资源的数据来源，在应用沙箱下的uri。示例fileUri为：'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg'。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900002	No such file.
14000011	System inner fail.
14000016	Operation Not Support.

示例：

async function example() {
  console.info('addResourceByFileUriDemo');
  try {
    let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE;
    let extension: string = 'jpg';
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension);
    // 需要确保fileUri对应的资源存在。
    let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg';
    assetChangeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, fileUri);
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('addResourceByFileUri successfully');
  } catch (err) {
    console.error(`addResourceByFileUriDemo failed with error: ${err.code}, ${err.message}`);
  }
}

addResource¹¹⁺

addResource(type: ResourceType, data: ArrayBuffer): void

通过ArrayBuffer数据添加资源。

注意：对于同一个资产变更请求，不支持在成功添加资源后，重复调用该接口。对于动态照片，可调用两次该接口分别添加图片和视频资源。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
type	ResourceType	是	待添加资源的类型。
data	ArrayBuffer	是	待添加资源的数据。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.
14000016	Operation Not Support.

示例：

async function example() {
  console.info('addResourceByArrayBufferDemo');
  try {
    let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE;
    let extension: string = 'jpg';
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension);
    let buffer: ArrayBuffer = new ArrayBuffer(2048);
    assetChangeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, buffer);
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('addResourceByArrayBuffer successfully');
  } catch (err) {
    console.error(`addResourceByArrayBufferDemo failed with error: ${err.code}, ${err.message}`);
  }
}

saveCameraPhoto¹²⁺

saveCameraPhoto(): void

保存相机拍摄的照片。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

接口抛出错误码的详细介绍请参见文件管理错误码。

错误码ID	错误信息
14000011	System inner fail.
14000016	Operation Not Support.

示例：

async function example(asset: photoAccessHelper.PhotoAsset) {
  console.info('saveCameraPhotoDemo');
  try {
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset);
    assetChangeRequest.saveCameraPhoto();
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('apply saveCameraPhoto successfully');
  } catch (err) {
    console.error(`apply saveCameraPhoto failed with error: ${err.code}, ${err.message}`);
  }
}

saveCameraPhoto¹³⁺

saveCameraPhoto(imageFileType: ImageFileType): void

保存相机拍摄的照片。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
imageFileType	ImageFileType	是	需要保存的类型。

错误码：

接口抛出错误码的详细介绍请参见文件管理错误码。

错误码ID	错误信息
14000011	System inner fail.
14000016	Operation Not Support.

示例：

import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { dataSharePredicates } from '@kit.ArkData';
import { image } from '@kit.ImageKit';

async function example(asset: photoAccessHelper.PhotoAsset) {
  console.info('saveCameraPhotoDemo');
  try {
    let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset);
    assetChangeRequest.saveCameraPhoto(photoAccessHelper.ImageFileType.JPEG);
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('apply saveCameraPhoto successfully');
  } catch (err) {
    console.error(`apply saveCameraPhoto failed with error: ${err.code}, ${err.message}`);
  }
}

discardCameraPhoto¹²⁺

discardCameraPhoto(): void

丢弃相机拍摄的照片。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

接口抛出错误码的详细介绍请参见文件管理错误码。

错误码ID	错误信息
14000011	Internal system error.
14000016	Operation Not Support.

示例：

async function example(asset: photoAccessHelper.PhotoAsset) {
  console.info('discardCameraPhotoDemo');
  try {
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset);
    assetChangeRequest.discardCameraPhoto();
    await phAccessHelper.applyChanges(assetChangeRequest);
    console.info('apply discardCameraPhoto successfully');
  } catch (err) {
    console.error(`apply discardCameraPhoto failed with error: ${err.code}, ${err.message}`);
  }
}

setOrientation¹⁵⁺

setOrientation(orientation: number): void

修改图片的旋转角度。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
orientation	number	是	待修改的图片旋转角度，且只能为0、90、180、270。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error.

示例：

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

async function example() {
  console.info('setOrientationDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
  let asset = await fetchResult.getFirstObject();
  let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset);
  assetChangeRequest.setOrientation(90);
  phAccessHelper.applyChanges(assetChangeRequest).then(() => {
    console.info('apply setOrientation successfully');
  }).catch((err: BusinessError) => {
    console.error(`apply setOrientation failed with error: ${err.code}, ${err.message}`);
  });
}

MediaAlbumChangeRequest¹¹⁺

相册变更请求。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

constructor¹¹⁺

constructor(album: Album)

构造函数。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
album	Album	是	需要变更的相册。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('MediaAlbumChangeRequest constructorDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
  let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
  let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
}

getAlbum¹¹⁺

getAlbum(): Album

获取当前相册变更请求中的相册。

注意：对于创建相册的变更请求，在调用applyChanges提交生效之前，该接口返回null。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
Album	返回当前相册变更请求中的相册。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14000011	System inner fail.

示例：

async function example() {
  console.info('getAlbumDemo');
  try {
    // 请确保图库内存在用户相册。
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
    let changeRequestAlbum: photoAccessHelper.Album = albumChangeRequest.getAlbum();
    console.info('change request album uri: ' + changeRequestAlbum.albumUri);
  } catch (err) {
    console.error(`getAlbumDemo failed with error: ${err.code}, ${err.message}`);
  }
}

setAlbumName¹¹⁺

setAlbumName(name: string): void

设置相册名称。

相册名的参数规格为：

相册名字符串长度为1~255。
不允许出现非法字符，包括：
. \ / : * ? " ' ` < > | { } [ ]
英文字符大小写不敏感。
相册名不允许重名。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
name	string	是	待设置的相册名称。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

async function example() {
  console.info('setAlbumNameDemo');
  try {
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
    let newAlbumName: string = 'newAlbumName' + new Date().getTime();
    albumChangeRequest.setAlbumName(newAlbumName);
    await phAccessHelper.applyChanges(albumChangeRequest);
    console.info('setAlbumName successfully');
  } catch (err) {
    console.error(`setAlbumNameDemo failed with error: ${err.code}, ${err.message}`);
  }
}

addAssets¹¹⁺

addAssets(assets: Array<PhotoAsset>): void

向相册中添加资产。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
assets	Array<PhotoAsset>	是	待添加到相册中的资产数组，最大数量300。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.
14000016	Operation Not Support.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('addAssetsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    // 请确保图库内存在用户相册和照片。
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
    albumChangeRequest.addAssets([asset]);
    await phAccessHelper.applyChanges(albumChangeRequest);
    console.info('addAssets successfully');
  } catch (err) {
    console.error(`addAssetsDemo failed with error: ${err.code}, ${err.message}`);
  }
}

removeAssets¹¹⁺

removeAssets(assets: Array<PhotoAsset>): void

从相册中移除资产。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
assets	Array<PhotoAsset>	是	待从相册中移除的资产数组，最大数量300。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.
14000016	Operation Not Support.

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  console.info('removeAssetsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();

    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
    albumChangeRequest.removeAssets([asset]);
    await phAccessHelper.applyChanges(albumChangeRequest);
    console.info('removeAssets successfully');
  } catch (err) {
    console.error(`removeAssetsDemo failed with error: ${err.code}, ${err.message}`);
  }
}

MediaAssetManager¹¹⁺

媒体资产管理类，管理各种媒体资源的读取操作。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

requestImage¹¹⁺

static requestImage(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: MediaAssetDataHandler<image.ImageSource>): Promise<string>

根据不同的策略模式，请求图片资源。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求图片资源，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的图片资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
asset	PhotoAsset	是	待请求的的媒体文件对象。
requestOptions	RequestOptions	是	图片请求策略模式配置项。
dataHandler	MediaAssetDataHandler<image.ImageSource>	是	媒体资源处理器，当所请求的图片资源准备完成时会触发回调。

返回值：

类型	说明
Promise<string>	Promise对象，返回请求id，可用于cancelRequest取消请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

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

class MediaHandler implements photoAccessHelper.MediaAssetDataHandler<image.ImageSource> {
  onDataPrepared(data: image.ImageSource) {
    if (data === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    console.info('on image data prepared');
  }
}

async function example() {
  console.info('requestImage');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.HIGH_QUALITY_MODE,
  }
  const handler = new MediaHandler();

  phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      await photoAccessHelper.MediaAssetManager.requestImage(context, photoAsset, requestOptions, handler);
      console.info('requestImage successfully');
  });
}

requestImageData¹¹⁺

static requestImageData(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: MediaAssetDataHandler<ArrayBuffer>): Promise<string>

根据不同的策略模式，请求图片资源数据。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求图片资源数据，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的图片资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
asset	PhotoAsset	是	待请求的的媒体文件对象。
requestOptions	RequestOptions	是	图片请求策略模式配置项。
dataHandler	MediaAssetDataHandler<ArrayBuffer>	是	媒体资源处理器，当所请求的图片资源准备完成时会触发回调。

返回值：

类型	说明
Promise<string>	Promise对象，返回请求id，可用于cancelRequest取消请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> {
  onDataPrepared(data: ArrayBuffer) {
    if (data === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    console.info('on image data prepared');
  }
}

async function example() {
  console.info('requestImageData');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.HIGH_QUALITY_MODE,
  }
  const handler = new MediaDataHandler();

  phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      await photoAccessHelper.MediaAssetManager.requestImageData(context, photoAsset, requestOptions, handler);
      console.info('requestImageData successfully');
  });
}

requestMovingPhoto¹²⁺

static requestMovingPhoto(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: MediaAssetDataHandler<MovingPhoto>): Promise<string>

根据不同的策略模式，请求动态照片对象。动态照片对象可用于请求动态照片的资源数据。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求动态照片对象，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的动态照片资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
asset	PhotoAsset	是	待请求的的媒体文件对象。
requestOptions	RequestOptions	是	图片请求策略模式配置项。
dataHandler	MediaAssetDataHandler<MovingPhoto>	是	媒体资源处理器，当所请求的图片资源准备完成时会触发回调。

返回值：

类型	说明
Promise<string>	Promise对象，返回请求id，可用于cancelRequest取消请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail

示例：

import { dataSharePredicates } from '@kit.ArkData';

class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
  async onDataPrepared(movingPhoto: photoAccessHelper.MovingPhoto) {
    if (movingPhoto === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    console.info("moving photo acquired successfully, uri: " + movingPhoto.getUri());
  }
}

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_SUBTYPE, photoAccessHelper.PhotoSubtype.MOVING_PHOTO);
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  // 请确保图库内存在动态照片。
  let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let asset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE,
  }
  const handler = new MovingPhotoHandler();
  try {
    let requestId: string = await photoAccessHelper.MediaAssetManager.requestMovingPhoto(context, asset, requestOptions, handler);
    console.info("moving photo requested successfully, requestId: " + requestId);
  } catch (err) {
    console.error(`failed to request moving photo, error code is ${err.code}, message is ${err.message}`);
  }
}

requestVideoFile¹²⁺

static requestVideoFile(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, fileUri: string, dataHandler: MediaAssetDataHandler<boolean>): Promise<string>

根据不同的策略模式，请求视频资源数据到沙箱路径。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求视频资源数据到应用沙箱，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的视频资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
asset	PhotoAsset	是	待请求的的媒体文件对象。
requestOptions	RequestOptions	是	视频请求策略模式配置项。
fileUri	string	是	目标写入沙箱路径Uri。示例fileUri为：'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.mp4'。
dataHandler	MediaAssetDataHandler<boolean>	是	媒体资源处理器，当所请求的视频资源写入完成时会触发回调。

返回值：

类型	说明
Promise<string>	Promise对象，返回请求id，可用于cancelRequest取消请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801¹⁵⁺	Capability not supported.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';
class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<boolean> {
    onDataPrepared(data: boolean) {
        console.info('on video request status prepared');
    }
}

async function example() {
  console.info('requestVideoFile');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.HIGH_QUALITY_MODE,
  }
  const handler = new MediaDataHandler();
  let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.mp4';
  phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      await photoAccessHelper.MediaAssetManager.requestVideoFile(context, photoAsset, requestOptions, fileUri, handler);
      console.info('requestVideoFile successfully');
  });
}

cancelRequest¹²⁺

static cancelRequest(context: Context, requestId: string): Promise<void>

取消尚未触发回调的资产内容请求。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
requestId	string	是	需要取消的请求id，requestImage等接口返回的有效requestId。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail

示例：

import { dataSharePredicates } from '@kit.ArkData';

async function example() {
  try {
    let requestId: string = 'xxx-xxx'; // 应用需使用requestImage等接口返回的有效requestId
    await photoAccessHelper.MediaAssetManager.cancelRequest(context, requestId);
    console.info("request cancelled successfully");
  } catch (err) {
    console.error(`cancelRequest failed with error: ${err.code}, ${err.message}`);
  }
}

loadMovingPhoto¹²⁺

static loadMovingPhoto(context: Context, imageFileUri: string, videoFileUri: string): Promise<MovingPhoto>

加载应用沙箱的动态照片。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
context	Context	是	传入AbilityContext或者UIExtensionContext的实例。
imageFileUri	string	是	应用沙箱动态照片的图片uri。
videoFileUri	string	是	应用沙箱动态照片的视频uri。

返回值：

类型	说明
Promise<MovingPhoto>	Promise对象，返回MovingPhoto实例。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error.

示例：

async function example() {
  try {
    let imageFileUri: string = 'file://com.example.temptest/data/storage/el2/base/haps/ImageFile.jpg'; // 应用沙箱动态照片的图片uri。
    let videoFileUri: string = 'file://com.example.temptest/data/storage/el2/base/haps/VideoFile.mp4'; // 应用沙箱动态照片的视频uri。
    let movingPhoto: photoAccessHelper.MovingPhoto = await photoAccessHelper.MediaAssetManager.loadMovingPhoto(context, imageFileUri, videoFileUri);
  } catch (err) {
    console.error(`loadMovingPhoto failed with error: ${err.code}, ${err.message}`);
  }
}

quickRequestImage¹³⁺

static quickRequestImage(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: QuickImageDataHandler<image.Picture>): Promise<string>

根据不同的策略模式，快速请求图片资源。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求图片资源，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。

参数：

参数名	类型	必填	说明
context	Context	是	传入Ability实例的Context。
asset	PhotoAsset	是	待请求的的媒体文件对象。
requestOptions	RequestOptions	是	图片请求策略模式配置项。
dataHandler	QuickImageDataHandler<image.Picture>	是	媒体资源处理器，当所请求的图片资源准备完成时会触发回调。

返回值：

类型	说明
Promise<string>	Promise对象，返回请求id，可用于cancelRequest取消请求。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error.

示例：

import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { dataSharePredicates } from '@kit.ArkData';
import { image } from '@kit.ImageKit';

class MediaHandler implements photoAccessHelper.QuickImageDataHandler<image.Picture> {
  onDataPrepared(data: image.Picture, imageSource: image.ImageSource, map: Map<string, string>) {
    console.info('on image data prepared');
  }
}

async function example() {
  console.info('quickRequestImage');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.HIGH_QUALITY_MODE,
  }
  const handler = new MediaHandler();
  let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
  phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => {
      console.info('fetchResult success');
      let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
      await photoAccessHelper.MediaAssetManager.quickRequestImage(context, photoAsset, requestOptions, handler);
      console.info('quickRequestImage successfully');
  });
}

MediaAssetDataHandler¹¹⁺

媒体资源处理器，应用在onDataPrepared方法中可自定义媒体资源处理逻辑。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

onDataPrepared¹¹⁺

onDataPrepared(data: T, map?: Map<string, string>): void

媒体资源就绪通知，当所请求的资源准备就绪时系统会回调此方法。如果资源准备出错，则回调的data为undefined。每个资源请求与回调一一对应。 T支持ArrayBuffer, ImageSource, MovingPhoto和boolean四种数据类型。其中，ArrayBuffer表示图片/视频资源数据，ImageSource表示图片源，MovingPhoto表示动态照片对象，boolean表示图片/视频资源是否成功写入应用沙箱。

map支持返回的信息：

map键名	值说明
'quality'	图片质量。高质量为'high'，低质量为'low'。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
data	T	是	已就绪的图片资源数据。泛型，支持ArrayBuffer, ImageSource, MovingPhoto和boolean四种数据类型。
map¹²⁺	Map<string, string>	否	用于获取图片资源的额外信息，如图片质量。

示例

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

class MediaHandler implements photoAccessHelper.MediaAssetDataHandler<image.ImageSource> {
  onDataPrepared = (data: image.ImageSource, map: Map<string, string>) => {
    if (data === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    // 自定义对ImageSource的处理逻辑。
    console.info('on image data prepared, photo quality is ' + map['quality']);
  }
}

class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> {
  onDataPrepared = (data: ArrayBuffer, map: Map<string, string>) => {
    if (data === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    // 自定义对ArrayBuffer的处理逻辑。
    console.info('on image data prepared, photo quality is ' + map['quality']);
  }
}

class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
  onDataPrepared = (data: photoAccessHelper.MovingPhoto, map: Map<string, string>) => {
    if (data === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    // 自定义对MovingPhoto的处理逻辑。
    console.info('on image data prepared, photo quality is ' + map['quality']);
  }
}

QuickImageDataHandler¹³⁺

媒体资源处理器，应用在onDataPrepared方法中可自定义媒体资源处理逻辑。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

onDataPrepared¹³⁺

onDataPrepared(data: T, imageSource: image.ImageSource, map: Map<string, string>): void

媒体资源就绪通知，当所请求的图片资源准备就绪时系统会回调此方法。如果资源准备出错，则回调的data为undefined。 T支持Picture数据类型。

map支持返回的信息：

map键名	值说明
'quality'	图片质量。高质量为'high'，低质量为'low'。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
data	T	是	已就绪的图片资源数据。泛型，支持Picture数据类型。
imageSource	image.ImageSource	是	已就绪的图片资源数据。
map¹³⁺	Map<string, string>	是	用于获取图片资源的额外信息，如图片质量。当前仅支持'quality'。

示例

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

class MediaHandler implements photoAccessHelper.QuickImageDataHandler<image.Picture> {
  onDataPrepared(data: image.Picture, imageSource: image.ImageSource, map: Map<string, string>) {
    console.info('on image data prepared');
  }
}

MovingPhoto¹²⁺

动态照片对象。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

getUri¹²⁺

getUri(): string

获取动态照片的uri。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

返回值：

类型	说明
string	动态照片的uri。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14000011	System inner fail.

示例：

import { dataSharePredicates } from '@kit.ArkData';

class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
  async onDataPrepared(movingPhoto: photoAccessHelper.MovingPhoto) {
    if (movingPhoto === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    console.info("moving photo acquired successfully, uri: " + movingPhoto.getUri());
  }
}

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_SUBTYPE, photoAccessHelper.PhotoSubtype.MOVING_PHOTO);
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  // 请确保图库内存在动态照片。
  let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let asset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE,
  }
  const handler = new MovingPhotoHandler();
  try {
    let requestId: string = await photoAccessHelper.MediaAssetManager.requestMovingPhoto(context, asset, requestOptions, handler);
    console.info("moving photo requested successfully, requestId: " + requestId);
  } catch (err) {
    console.error(`failed to request moving photo, error code is ${err.code}, message is ${err.message}`);
  }
}

requestContent¹²⁺

requestContent(imageFileUri: string, videoFileUri: string): Promise<void>

同时请求动态照片的图片内容和视频内容，并写入参数指定的对应的uri中。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求动态照片对象并读取内容，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的动态照片资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
imageFileUri	string	是	待写入动态照片图片内容的uri。示例imageFileUri为："file://com.example.temptest/data/storage/el2/base/haps/ImageFile.jpg"。
videoFileUri	string	是	待写入动态照片视频内容的uri。示例videoFileUri为："file://com.example.temptest/data/storage/el2/base/haps/VideoFile.mp4"。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail

示例：

import { dataSharePredicates } from '@kit.ArkData';

class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
  async onDataPrepared(movingPhoto: photoAccessHelper.MovingPhoto) {
    if (movingPhoto === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    // 应用需要确保待写入的uri是有效的。
    let imageFileUri: string = "file://com.example.temptest/data/storage/el2/base/haps/ImageFile.jpg";
    let videoFileUri: string = "file://com.example.temptest/data/storage/el2/base/haps/VideoFile.mp4";
    try {
      await movingPhoto.requestContent(imageFileUri, videoFileUri);
      console.log("moving photo contents retrieved successfully");
    } catch (err) {
      console.error(`failed to retrieve contents of moving photo, error code is ${err.code}, message is ${err.message}`);
    }
  }
}

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_SUBTYPE, photoAccessHelper.PhotoSubtype.MOVING_PHOTO);
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  // 请确保图库内存在动态照片。
  let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let asset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE,
  }
  const handler = new MovingPhotoHandler();
  try {
    let requestId: string = await photoAccessHelper.MediaAssetManager.requestMovingPhoto(context, asset, requestOptions, handler);
    console.info("moving photo requested successfully, requestId: " + requestId);
  } catch (err) {
    console.error(`failed to request moving photo, error code is ${err.code}, message is ${err.message}`);
  }
}

requestContent¹²⁺

requestContent(resourceType: ResourceType, fileUri: string): Promise<void>

请求指定资源类型的动态照片内容，并写入参数指定的uri中。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求动态照片对象并读取内容，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的动态照片资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
resourceType	ResourceType	是	所请求动态照片内容的资源类型。
fileUri	string	是	待写入动态照片内容的uri。

返回值：

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

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail

示例：

import { dataSharePredicates } from '@kit.ArkData';

class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
  async onDataPrepared(movingPhoto: photoAccessHelper.MovingPhoto) {
    if (movingPhoto === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    // 应用需要确保待写入的uri是有效的。
    let imageFileUri: string = "file://com.example.temptest/data/storage/el2/base/haps/ImageFile.jpg";
    try {
      await movingPhoto.requestContent(photoAccessHelper.ResourceType.IMAGE_RESOURCE, imageFileUri);
      console.log("moving photo image content retrieved successfully");
    } catch (err) {
      console.error(`failed to retrieve image content of moving photo, error code is ${err.code}, message is ${err.message}`);
    }
  }
}

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_SUBTYPE, photoAccessHelper.PhotoSubtype.MOVING_PHOTO);
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  // 请确保图库内存在动态照片。
  let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let asset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE,
  }
  const handler = new MovingPhotoHandler();
  try {
    let requestId: string = await photoAccessHelper.MediaAssetManager.requestMovingPhoto(context, asset, requestOptions, handler);
    console.info("moving photo requested successfully, requestId: " + requestId);
  } catch (err) {
    console.error(`failed to request moving photo, error code is ${err.code}, message is ${err.message}`);
  }
}

requestContent¹²⁺

requestContent(resourceType: ResourceType): Promise<ArrayBuffer>

请求指定资源类型的动态照片内容，以ArrayBuffer的形式返回。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

需要权限：ohos.permission.READ_IMAGEVIDEO

通过picker的方式调用该接口来请求动态照片对象并读取内容，不需要申请'ohos.permission.READ_IMAGEVIDEO'权限，详情请参考开发指南。
对于本应用保存到媒体库的动态照片资源，应用无需额外申请'ohos.permission.READ_IMAGEVIDEO'权限即可访问。

参数：

参数名	类型	必填	说明
resourceType	ResourceType	是	所请求动态照片内容的资源类型。

返回值：

类型	说明
Promise<ArrayBuffer>	Promise对象，返回包含所请求文件内容的ArrayBuffer。

错误码：

接口抛出错误码的详细介绍请参见通用错误码和文件管理错误码。

错误码ID	错误信息
201	Permission denied
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail

示例：

import { dataSharePredicates } from '@kit.ArkData';

class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
  async onDataPrepared(movingPhoto: photoAccessHelper.MovingPhoto) {
    if (movingPhoto === undefined) {
      console.error('Error occurred when preparing data');
      return;
    }
    try {
      let buffer: ArrayBuffer = await movingPhoto.requestContent(photoAccessHelper.ResourceType.IMAGE_RESOURCE);
      console.log("moving photo image content retrieved successfully, buffer length: " + buffer.byteLength);
    } catch (err) {
      console.error(`failed to retrieve image content of moving photo, error code is ${err.code}, message is ${err.message}`);
    }
  }
}

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_SUBTYPE, photoAccessHelper.PhotoSubtype.MOVING_PHOTO);
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  // 请确保图库内存在动态照片。
  let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
  let asset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
  let requestOptions: photoAccessHelper.RequestOptions = {
    deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE,
  }
  const handler = new MovingPhotoHandler();
  try {
    let requestId: string = await photoAccessHelper.MediaAssetManager.requestMovingPhoto(context, asset, requestOptions, handler);
    console.info("moving photo requested successfully, requestId: " + requestId);
  } catch (err) {
    console.error(`failed to request moving photo, error code is ${err.code}, message is ${err.message}`);
  }
}

MemberType

type MemberType = number | string | boolean

PhotoAsset的成员类型。

成员类型为下表类型中的并集。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

类型	说明
number	表示值类型为数字，可取任意值。
string	表示值类型为字符，可取任意值。
boolean	表示值类型为布尔类型。

PhotoType

枚举，媒体文件类型。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
IMAGE	1	图片。
VIDEO	2	视频。

PhotoSubtype¹²⁺

枚举，不同PhotoAsset的类型。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
DEFAULT	0	默认照片类型。
MOVING_PHOTO	3	动态照片文件类型。
BURST	4	连拍照片文件类型。

DynamicRangeType¹²⁺

枚举，媒体文件的动态范围类型。

系统能力: SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
SDR	0	标准动态范围类型。
HDR	1	高动态范围类型。

AlbumType

枚举，相册类型，表示是用户相册还是系统预置相册。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
USER	0	用户相册。
SYSTEM	1024	系统预置相册。

AlbumSubtype

枚举，相册子类型，表示具体的相册类型。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
USER_GENERIC	1	用户相册。
FAVORITE	1025	收藏夹。
VIDEO	1026	视频相册。
IMAGE¹²⁺	1031	图片相册。
ANY	2147483647	任意相册。

PositionType¹⁶⁺

枚举，文件位置，表示文件在本地或云端。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
LOCAL	1	文件只存在于本端设备。
CLOUD	2	文件只存在于云端。
LOCAL_AND_CLOUD	3	文件存在于本端设备和云端。

PhotoKeys

枚举，图片和视频文件关键信息。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
URI	'uri'	文件uri。注意：查询照片时，该字段仅支持使用DataSharePredicates.equalTo谓词。
PHOTO_TYPE	'media_type'	媒体文件类型。
DISPLAY_NAME	'display_name'	显示名字。
SIZE	'size'	文件大小（单位：字节）。
DATE_ADDED	'date_added'	文件创建时的Unix时间戳（单位：秒）。
DATE_MODIFIED	'date_modified'	文件修改时的Unix时间戳（单位：秒）。修改文件名不会改变此值，当文件内容发生修改时才会更新。
DURATION	'duration'	持续时间（单位：毫秒）。
WIDTH	'width'	图片宽度（单位：像素）。
HEIGHT	'height'	图片高度（单位：像素）。
DATE_TAKEN	'date_taken'	拍摄时的Unix时间戳（单位：秒）。
ORIENTATION	'orientation'	文件的旋转角度，单位为度。
FAVORITE	'is_favorite'	收藏。
TITLE	'title'	文件标题。
DATE_ADDED_MS¹²⁺	'date_added_ms'	文件创建时的Unix时间戳（单位：毫秒）。注意：查询照片时，不支持基于该字段排序。
DATE_MODIFIED_MS¹²⁺	'date_modified_ms'	文件修改时的Unix时间戳（单位：毫秒）。修改文件名不会改变此值，当文件内容发生修改时才会更新。注意：查询照片时，不支持基于该字段排序。
PHOTO_SUBTYPE¹²⁺	'subtype'	媒体文件的子类型。
DYNAMIC_RANGE_TYPE¹²⁺	'dynamic_range_type'	媒体文件的动态范围类型。
COVER_POSITION¹²⁺	'cover_position'	动态照片的封面位置，具体表示封面帧所对应的视频时间戳（单位：微秒）。
BURST_KEY¹²⁺	'burst_key'	一组连拍照片的唯一标识：uuid。
LCD_SIZE¹²⁺	'lcd_size'	LCD图片的宽高，值为width:height拼接而成的字符串。
THM_SIZE¹²⁺	'thm_size'	THUMB图片的宽高，值为width:height拼接而成的字符串。
DETAIL_TIME¹³⁺	'detail_time'	大图浏览时间，值为拍摄时对应时区的时间的字符串，不会跟随时区变化。
DATE_TAKEN_MS¹³⁺	'date_taken_ms'	拍摄时的Unix时间戳（单位：毫秒）。
POSITION¹⁶⁺	'position'	文件位置类型。

AlbumKeys

枚举，相册关键信息。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
URI	'uri'	相册uri。
ALBUM_NAME	'album_name'	相册名字。

CreateOptions

图片或视频的创建选项。

title参数规格为：

不应包含扩展名。
文件名字符串长度为1~255。
文件名中不允许出现的非法英文字符，包括：
. .. \ / : * ? " ' ` < > | { } [ ]

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	必填	说明
title	string	否	图片或者视频的标题。
subtype¹²⁺	PhotoSubtype	否	图片或者视频的文件子类型。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

FetchOptions

检索条件。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	可读	可写	说明
fetchColumns	Array<string>	是	是	检索条件，指定列名查询。对于照片，如果该参数为空，默认查询'uri'、'media_type'、'subtype'和'display_name'，使用get接口获取当前对象的其他属性时将会报错。示例：fetchColumns: ['uri', 'title']。对于相册，如果该参数为空，默认查询'uri'和'album_name'。字符串长度为1~255。
predicates	dataSharePredicates.DataSharePredicates	是	是	谓词查询，显示过滤条件。

RequestOptions¹¹⁺

请求策略。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	只读	可选	说明
deliveryMode	DeliveryMode	否	否	请求资源分发模式，可以指定对于该资源的请求策略，可被配置为快速模式，高质量模式，均衡模式三种策略。
compatibleMode¹⁵⁺	CompatibleMode	否	是	配置HDR视频转码模式，可指定配置为转码和不转码两种策略。
mediaAssetProgressHandler¹⁵⁺	MediaAssetProgressHandler	否	是	配置HDR视频转码为SDR视频时的进度级回调。

MediaChangeRequest¹¹⁺

媒体变更请求，资产变更请求和相册变更请求的父类型。

注意：媒体变更请求需要在调用applyChanges后才会提交生效。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

ResourceType¹¹⁺

枚举，写入资源的类型。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
IMAGE_RESOURCE	1	表示图片资源。
VIDEO_RESOURCE	2	表示视频资源。

ImageFileType¹³⁺

枚举，图片保存类型。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
JPEG	1	表示jpeg图片类型。
HEIF	2	表示heif图片类型。

ChangeData

监听器回调函数的值。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	可读	可写	说明
type	NotifyType	是	否	ChangeData的通知类型。
uris	Array<string>	是	否	相同NotifyType的所有uri，可以是PhotoAsset或Album。
extraUris	Array<string>	是	否	相册中变动文件的uri数组。

NotifyType

枚举，通知事件的类型。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
NOTIFY_ADD	0	添加文件集或相册通知的类型。
NOTIFY_UPDATE	1	文件集或相册的更新通知类型。
NOTIFY_REMOVE	2	删除文件集或相册的通知类型。
NOTIFY_ALBUM_ADD_ASSET	3	在相册中添加的文件集的通知类型。
NOTIFY_ALBUM_REMOVE_ASSET	4	在相册中删除的文件集的通知类型。

DefaultChangeUri

枚举，DefaultChangeUri子类型。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
DEFAULT_PHOTO_URI	'file://media/Photo'	默认PhotoAsset的Uri，与forSubUri{true}一起使用，将接收所有PhotoAsset的更改通知。
DEFAULT_ALBUM_URI	'file://media/PhotoAlbum'	默认相册的Uri，与forSubUri{true}一起使用，将接收所有相册的更改通知。

PhotoViewMIMETypes

枚举，可选择的媒体文件类型。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
IMAGE_TYPE	'image/*'	图片类型。
VIDEO_TYPE	'video/*'	视频类型。
IMAGE_VIDEO_TYPE	'/'	图片和视频类型。
MOVING_PHOTO_IMAGE_TYPE¹²⁺	'image/movingPhoto'	动态照片类型。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

RecommendationType¹¹⁺

枚举，推荐的图片类型。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
QR_OR_BAR_CODE	1	二维码或条码。
QR_CODE	2	二维码。
BAR_CODE	3	条码。
ID_CARD	4	身份证。
PROFILE_PICTURE	5	头像。
PASSPORT¹²⁺	6	护照。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
BANK_CARD¹²⁺	7	银行卡。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
DRIVER_LICENSE¹²⁺	8	驾驶证。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
DRIVING_LICENSE¹²⁺	9	行驶证。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
FEATURED_SINGLE_PORTRAIT¹²⁺	10	推荐人像。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
async function example() {
  try {
    let recommendOptions: photoAccessHelper.RecommendationOptions = {
      recommendationType: photoAccessHelper.RecommendationType.ID_CARD
    }
    let options: photoAccessHelper.PhotoSelectOptions = {
      MIMEType: photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE,
      maxSelectNumber: 1,
      recommendationOptions: recommendOptions
    }
    let photoPicker = new photoAccessHelper.PhotoViewPicker();
    photoPicker.select(options).then((PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => {
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
    }).catch((err: BusinessError) => {
      console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`);
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`);
  }
}

TextContextInfo¹²⁺

文本信息，用于推荐图片的文本信息。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	必填	说明
text	string	否	如果需要根据文本(支持250字以内的简体中文)推荐相应的图片，则配置此参数。text默认是空字符串。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
async function example() {
  try {
    let textInfo: photoAccessHelper.TextContextInfo = {
      text: '上海野生动物园的大熊猫'
    }
    let recommendOptions: photoAccessHelper.RecommendationOptions = {
      textContextInfo: textInfo
    }
    let options: photoAccessHelper.PhotoSelectOptions = {
      MIMEType: photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE,
      maxSelectNumber: 1,
      recommendationOptions: recommendOptions
    }
    let photoPicker = new photoAccessHelper.PhotoViewPicker();
    photoPicker.select(options).then((PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => {
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
    }).catch((err: BusinessError) => {
      console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`);
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`);
  }
}

RecommendationOptions¹¹⁺

图片推荐选项(基于图片数据分析结果，依赖设备适配)。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	必填	说明
recommendationType	RecommendationType	否	如果需要根据枚举值推荐相应的图片，则配置此参数。
textContextInfo¹²⁺	TextContextInfo	否	如果需要根据文本信息推荐相应的图片，则配置此参数(如果同时配置了recommendationType，则仅textContextInfo生效)。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

BaseSelectOptions¹²⁺

图库选择选项基类。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	必填	说明
MIMEType¹⁰⁺	PhotoViewMIMETypes	否	可选择的媒体文件类型，若无此参数，则默认为图片和视频类型。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
maxSelectNumber¹⁰⁺	number	否	选择媒体文件数量的最大值(最大可设置的值为500，若不设置则默认为50)。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
isPhotoTakingSupported¹¹⁺	boolean	否	是否支持拍照，true表示支持，false表示不支持，默认为true。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
isSearchSupported¹¹⁺	boolean	否	是否支持搜索，true表示支持，false表示不支持，默认为true。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
recommendationOptions¹¹⁺	RecommendationOptions	否	图片推荐相关配置参数。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
preselectedUris¹¹⁺	Array<string>	否	预选择图片的uri数据。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
isPreviewForSingleSelectionSupported¹²⁺	boolean	否	单选模式下是否需要进大图预览，true表示需要，false表示不需要，默认为true。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

PhotoSelectOptions

图库选择选项子类，继承于BaseSelectOptions。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	必填	说明
isEditSupported¹¹⁺	boolean	否	是否支持编辑照片，true表示支持，false表示不支持，默认为true。
isOriginalSupported¹²⁺	boolean	否	是否显示选择原图按钮，true表示显示，false表示不显示，默认为false。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
subWindowName¹²⁺	string	否	子窗窗口名称。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
completeButtonText¹⁴⁺	CompleteButtonText	否	完成按钮显示的内容。完成按钮指在界面右下方，用户点击表示图片选择已完成的按钮。原子化服务API：从API version 14开始，该接口支持在原子化服务中使用。

PhotoSelectResult

返回图库选择后的结果集。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	可读	可写	说明
photoUris	Array<string>	是	是	返回图库选择后的媒体文件的uri数组，此uri数组只能通过临时授权的方式调用photoAccessHelper.getAssets接口去使用，具体使用方式参见用户文件uri介绍中的媒体文件uri的使用方式。
isOriginalPhoto	boolean	是	是	返回图库选择后的媒体文件是否为原图。

DeliveryMode¹¹⁺

枚举，资源分发模式。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
FAST_MODE	0	快速模式。
HIGH_QUALITY_MODE	1	高质量模式。
BALANCE_MODE	2	均衡模式。

PhotoCreationConfig¹²⁺

保存图片/视频到媒体库的配置，包括保存的文件名等。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	必填	说明
title	string	否	图片或者视频的标题。参数规格为： - 不应包含扩展名。 - 文件名字符串长度为1~255（资产文件名为标题+扩展名）。 - 不允许出现非法字符，包括：. \ / : * ? " ' ` < > \| { } [ ]
fileNameExtension	string	是	文件扩展名，例如'jpg'。
photoType	PhotoType	是	创建的文件类型PhotoType，IMAGE或者VIDEO。
subtype	PhotoSubtype	否	图片或者视频的文件子类型PhotoSubtype，当前仅支持DEFAULT。

CompatibleMode¹⁵⁺

配置转码模式。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
ORIGINAL_FORMAT_MODE	0	原视频资源内容模式。
COMPATIBLE_FORMAT_MODE	1	兼容模式，从HDR视频转换为SDR视频。

CompleteButtonText¹⁴⁺

配置完成按钮显示内容。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
TEXT_DONE¹⁴⁺	0	显示“完成”。原子化服务API：从API version 14开始，该接口支持在原子化服务中使用。
TEXT_SEND¹⁴⁺	1	显示“发送”。原子化服务API：从API version 14开始，该接口支持在原子化服务中使用。
TEXT_ADD¹⁴⁺	2	显示“添加”。原子化服务API：从API version 14开始，该接口支持在原子化服务中使用。

MediaAssetProgressHandler¹⁵⁺

媒体资产进度处理器，应用在onProgress方法中获取媒体资产进度。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

onProgress¹⁵⁺

onProgress(progress: number): void

当所请求的视频资源返回进度时系统会回调此方法。

系统能力：SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
progress	number	是	返回的进度百分比，范围为0~100。

@ohos.file.photoAccessHelper (相册管理模块)

导入模块

photoAccessHelper.getPhotoAccessHelper

PhotoAccessHelper

getAssets

getAssets

getBurstAssets12+

createAsset

createAsset

createAsset

getAlbums

getAlbums

getAlbums

registerChange

unRegisterChange

createDeleteRequest(deprecated)

createDeleteRequest(deprecated)

applyChanges11+

release

release

showAssetsCreationDialog12+

createAssetWithShortTermPermission12+

requestPhotoUrisReadPermission14+

getSupportedPhotoFormats18+

PhotoAsset

属性

get

set

commitModify

commitModify

getReadOnlyFd(deprecated)

getReadOnlyFd(deprecated)

close(deprecated)

close(deprecated)

getThumbnail

getThumbnail

getThumbnail

clone14+

PhotoViewPicker

select

select

select

FetchResult

getCount

isAfterLast

close

getFirstObject

getFirstObject

getNextObject

getNextObject

getLastObject

getLastObject

getObjectByPosition

getObjectByPosition

getAllObjects

getAllObjects

Album

属性

getAssets

getAssets

commitModify

commitModify

addAssets(deprecated)

addAssets(deprecated)

removeAssets(deprecated)

removeAssets(deprecated)

MediaAssetChangeRequest11+

constructor11+

createImageAssetRequest11+

createVideoAssetRequest11+

createAssetRequest11+

deleteAssets11+

deleteAssets11+

getAsset11+

setTitle11+

getWriteCacheHandler11+

addResource11+

addResource11+

saveCameraPhoto12+

saveCameraPhoto13+

getBurstAssets¹²⁺

createDeleteRequest^(deprecated)

createDeleteRequest^(deprecated)

applyChanges¹¹⁺

showAssetsCreationDialog¹²⁺

createAssetWithShortTermPermission¹²⁺

requestPhotoUrisReadPermission¹⁴⁺

getSupportedPhotoFormats¹⁸⁺

getReadOnlyFd^(deprecated)

getReadOnlyFd^(deprecated)

close^(deprecated)

close^(deprecated)

clone¹⁴⁺

addAssets^(deprecated)

addAssets^(deprecated)

removeAssets^(deprecated)

removeAssets^(deprecated)

MediaAssetChangeRequest¹¹⁺

constructor¹¹⁺

createImageAssetRequest¹¹⁺

createVideoAssetRequest¹¹⁺

createAssetRequest¹¹⁺

deleteAssets¹¹⁺

deleteAssets¹¹⁺

getAsset¹¹⁺

setTitle¹¹⁺

getWriteCacheHandler¹¹⁺

addResource¹¹⁺

addResource¹¹⁺

saveCameraPhoto¹²⁺

saveCameraPhoto¹³⁺

discardCameraPhoto¹²⁺

setOrientation¹⁵⁺

MediaAlbumChangeRequest¹¹⁺

constructor¹¹⁺

getAlbum¹¹⁺

setAlbumName¹¹⁺

addAssets¹¹⁺

removeAssets¹¹⁺

MediaAssetManager¹¹⁺

requestImage¹¹⁺

requestImageData¹¹⁺

requestMovingPhoto¹²⁺

requestVideoFile¹²⁺

cancelRequest¹²⁺

loadMovingPhoto¹²⁺

quickRequestImage¹³⁺

MediaAssetDataHandler¹¹⁺

onDataPrepared¹¹⁺

QuickImageDataHandler¹³⁺

onDataPrepared¹³⁺

MovingPhoto¹²⁺

getUri¹²⁺

requestContent¹²⁺

requestContent¹²⁺

requestContent¹²⁺

PhotoSubtype¹²⁺

DynamicRangeType¹²⁺

PositionType¹⁶⁺

RequestOptions¹¹⁺

MediaChangeRequest¹¹⁺

ResourceType¹¹⁺

ImageFileType¹³⁺

RecommendationType¹¹⁺

TextContextInfo¹²⁺

RecommendationOptions¹¹⁺

BaseSelectOptions¹²⁺

DeliveryMode¹¹⁺

PhotoCreationConfig¹²⁺

CompatibleMode¹⁵⁺

CompleteButtonText¹⁴⁺

MediaAssetProgressHandler¹⁵⁺

onProgress¹⁵⁺