@ohos.file.photoAccessHelper (Album Management)

The photoAccessHelper module provides APIs for album management, including creating an album and accessing and modifying media data in an album.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

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

photoAccessHelper.getPhotoAccessHelper

getPhotoAccessHelper(context: Context): PhotoAccessHelper

Obtains a PhotoAccessHelper instance for accessing and modifying media files in the album.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

// The phAccessHelper instance obtained is a global object. It is used by default in subsequent operations. If the code snippet is not added, an error will be reported indicating that phAccessHelper is not defined.
let context = getContext(this);
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

PhotoAccessHelper

getAssets

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

Obtains image and video assets. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>>

Obtains image and video assets. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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}`);
  }
}

createAsset

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

Creates an image or video asset with the specified file type, file name extension, and options. This API uses an asynchronous callback to return the result.

If the application does not have the ohos.permission.WRITE_IMAGEVIDEO permission, you can use a security component to create a media asset. For details, see Creating a Media Asset Using a Security Component.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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

Creates an image or video asset with the specified file type and file name extension. This API uses an asynchronous callback to return the result.

If the application does not have the ohos.permission.WRITE_IMAGEVIDEO permission, you can use a security component to create a media asset. For details, see Creating a Media Asset Using a Security Component.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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>

Creates an image or video asset with the specified file type, file name extension, and options. This API uses a promise to return the result.

If the application does not have the ohos.permission.WRITE_IMAGEVIDEO permission, you can use a security component to create a media asset. For details, see Creating a Media Asset Using a Security Component.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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

Obtains albums based on the specified options and album type. This API uses an asynchronous callback to return the result.

Before the operation, ensure that the albums to obtain exist.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

async function example() {
  // Obtain the album named 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

Obtains albums by type. This API uses an asynchronous callback to return the result.

Before the operation, ensure that the albums to obtain exist.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  // Obtain the system album VIDEO, which is preset by default.
  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>>

Obtains albums based on the specified options and album type. This API uses a promise to return the result.

Before the operation, ensure that the albums to obtain exist.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

async function example() {
  // Obtain the album named 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

Registers listening for the specified URI. This API uses a callback to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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
  }
  // Register onCallback1.
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback1);
  // Register onCallback2.
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback2);

  photoAsset.setFavorite(true, (err) => {
    if (err === undefined) {
      console.info('setFavorite successfully');
    } else {
      console.error(`setFavorite failed with error: ${err.code}, ${err.message}`);
    }
  });
}

unRegisterChange

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

Unregisters listening for the specified URI. Multiple callbacks can be registered for a URI for listening. You can use this API to unregister the listening of the specified callbacks or all callbacks.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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');
  }
  // Register onCallback1.
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback1);
  // Register onCallback2.
  phAccessHelper.registerChange(photoAsset.uri, false, onCallback2);
  // Unregister the listening of onCallback1.
  phAccessHelper.unRegisterChange(photoAsset.uri, onCallback1);
  photoAsset.setFavorite(true, (err) => {
    if (err === undefined) {
      console.info('setFavorite successfully');
    } else {
      console.error(`setFavorite failed with error: ${err.code}, ${err.message}`);
    }
  });
}

createDeleteRequest^(deprecated)

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

Creates a dialog box for deleting media files. This API uses an asynchronous callback to return the result. The deleted media files are moved to the trash.

NOTE

This API is supported since API version 10 and deprecated since API version 11. Use MediaAssetChangeRequest.deleteAssets instead.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Creates a dialog box for deleting media files. This API uses a promise to return the result. The deleted media files are moved to the trash.

NOTE

This API is supported since API version 10 and deprecated since API version 11. Use MediaAssetChangeRequest.deleteAssets instead.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Applies media changes. This API uses a promise to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

This API depends on the MediaChangeRequest object. For details about the sample code, see the examples of MediaAssetChangeRequest and MediaAlbumChangeRequest.

release

release(callback: AsyncCallback<void>): void

Releases this PhotoAccessHelper instance. This API uses an asynchronous callback to return the result. Call this API when the APIs of the PhotoAccessHelper instance are no longer used.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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>

Releases this PhotoAccessHelper instance. This API uses a promise to return the result. Call this API when the APIs of the PhotoAccessHelper instance are no longer used.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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}`);
  }
}

PhotoAsset

Provides APIs for encapsulating file asset attributes.

Attributes

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

get

get(member: string): MemberType;

Obtains a PhotoAsset member parameter.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Sets a PhotoAsset member parameter.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Commits the modification on the file metadata to the database. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Commits the modification on the file metadata to the database. This API uses a promise to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Opens this file in read-only mode. This API uses an asynchronous callback to return the result.

NOTE

• This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
• The returned FD must be closed when it is not required.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  console.info('getReadOnlyFdDemo');
  // Ensure that there are images and video files in the device.
  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>

Opens this file in read-only mode. This API uses a promise to return the result.

NOTE

• This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
• The returned FD must be closed when it is not required.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  console.info('getReadOnlyFdDemo');
  try {
    // Ensure that there are images and video files in the device.
    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

Closes a file. This API uses an asynchronous callback to return the result.

NOTE

• This API is supported since API version 10 and deprecated since API version 11.
• For security purposes, the API for obtaining the media file handle is no longer provided, and the corresponding close API is also deprecated.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Closes a file. This API uses a promise to return the result.

NOTE

This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided, and the corresponding close API is also deprecated.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the thumbnail of this file. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the file thumbnail of the given size. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import image from '@ohos.multimedia.image'

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>

Obtains the file thumbnail of the given size. This API uses a promise to return the result.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import image from '@ohos.multimedia.image'
import { BusinessError } from '@ohos.base';

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}`);
  });
}

PhotoViewPicker

Provides APIs for the user to select images and videos. Before using the APIs of PhotoViewPicker, you need to create a PhotoViewPicker instance.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Example

let photoPicker = new photoAccessHelper.PhotoViewPicker();

select

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

Starts a photoPicker page for the user to select one or more images or videos. This API uses a promise to return the result. You can pass in PhotoSelectOptions to specify the media file type and the maximum number of files to select.

NOTE
The photoUris in the PhotoSelectResult object returned by this API can be used only by calling photoAccessHelper.getAssets() with temporary authorization. For details, see Using a Media File URI.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
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

Starts a photoPicker page for the user to select one or more images or videos. This API uses an asynchronous callback to return the result. You can pass in PhotoSelectOptions to specify the media file type and the maximum number of files to select.

NOTE
The photoUris in the PhotoSelectResult object returned by this API can be used only by calling photoAccessHelper.getAssets() with temporary authorization. For details, see Using a Media File URI.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
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

Starts a photoPicker page for the user to select one or more images or videos. This API uses an asynchronous callback to return the result.

NOTE
The photoUris in the PhotoSelectResult object returned by this API can be used only by calling photoAccessHelper.getAssets() with temporary authorization. For details, see Using a Media File URI.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
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

Provides APIs to manage the file retrieval result.

getCount

getCount(): number

Obtains the total number of files in the result set.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Checks whether the cursor is in the last row of the result set.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Closes this FetchFileResult instance to invalidate it. After this instance is released, the APIs in this instance cannot be invoked.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the first file asset in the result set. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Obtains the first file asset in the result set. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the next file asset in the result set. This API uses an asynchronous callback to return the result. Before using this API, you must use isAfterLast() to check whether the current position is the end of the result set.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Obtains the next file asset in the result set. This API uses a promise to return the result. Before using this API, you must use isAfterLast() to check whether the current position is the end of the result set.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the last file asset in the result set. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Obtains the last file asset in the result set. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains a file asset with the specified index in the result set. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Obtains a file asset with the specified index in the result set. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains all the file assets in the result set. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>>

Obtains all the file assets in the result set. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Provides APIs to manage albums.

Attributes

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

getAssets

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

Obtains image and video assets. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>>

Obtains image and video assets. This API uses a promise to return the result.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

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

Commits the modification on the album attributes to the database. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Commits the modification on the album attributes to the database. This API uses a promise to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

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

Adds image and video assets to an album. Before the operation, ensure that the image and video assets to add and the album exist. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 10 and deprecated since API version 11. Use MediaAlbumChangeRequest.addAssets instead.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Adds image and video assets to an album. Before the operation, ensure that the image and video assets to add and the album exist. This API uses a promise to return the result.

NOTE

This API is supported since API version 10 and deprecated since API version 11. Use MediaAlbumChangeRequest.addAssets instead.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

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

Removes image and video assets from an album. The album and file resources must exist. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 10 and deprecated since API version 11. Use MediaAlbumChangeRequest.removeAssets instead.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Removes image and video assets from an album. The album and file resources must exist. This API uses a promise to return the result.

NOTE

This API is supported since API version 10 and deprecated since API version 11. Use MediaAlbumChangeRequest.removeAssets instead.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

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¹¹⁺

Represents a media asset change request.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

constructor¹¹⁺

constructor(asset: PhotoAsset)

Constructor.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Creates an image asset change request.

Use fileUri to specify the data source of the asset to be created. For details, see FileUri.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  console.info('createImageAssetRequestDemo');
  try {
    // Ensure that the asset specified by fileUri exists.
    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

Creates a video asset change request.

Use fileUri to specify the data source of the asset to be created. For details, see FileUri.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  console.info('createVideoAssetRequestDemo');
  try {
    // Ensure that the asset specified by fileUri exists.
    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

Create an asset change request based on the file type and filename extension.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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);
    // Ensure that the asset specified by fileUri exists.
    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>

Deletes media assets. This API uses a promise to return the result. The deleted assets are moved to the trash.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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>

Deletes media assets. This API uses a promise to return the result. The deleted assets are moved to the trash.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the asset in this asset change request.

NOTE
For the change request used to create an asset, this API returns null before applyChanges is called to apply the changes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  console.info('getAssetDemo');
  try {
    // Ensure that the asset specified by fileUri exists.
    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

Sets the media asset title.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Note that the title cannot:

• Contain the filename extension.
• Exceed 255 characters.
• Contain any of the following characters:
  . .. \ / : * ? " ' ` < > | { } [ ]

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { BusinessError } from '@ohos.base';

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>

Obtains the write handle of a temporary file.

NOTE
For the same asset change request, this API cannot be repeatedly called after a temporary file write handle is successfully obtained.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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

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 fs.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

Adds resources to the application sandbox directory using fileUri.

NOTE
For the same asset change request, this API cannot be repeatedly called after resources are successfully added.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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);
    // Ensure that the asset specified by fileUri exists.
    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

Adds resources using ArrayBuffer data.

NOTE
For the same asset change request, this API cannot be repeatedly called after resources are successfully added.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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}`);
  }
}

MediaAlbumChangeRequest¹¹⁺

Provides APIs for managing the media album change request.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

constructor¹¹⁺

constructor(album: Album)

Constructor.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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

Obtains the album in the current album change request.

NOTE
For the change request for creating an album, this API returns null before applyChanges is called to apply the changes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

async function example() {
  console.info('getAlbumDemo');
  try {
    let albumName: string = 'newAlbumName' + new Date().getTime();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
    await phAccessHelper.applyChanges(albumChangeRequest);
    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
    console.info('create album successfully with uri = ' + album.albumUri);
  } catch (err) {
    console.error(`getAlbumDemo failed with error: ${err.code}, ${err.message}`);
  }
}

setAlbumName¹¹⁺

setAlbumName(name: string): void

Sets the album name.

The album name must comply with the following specifications:

• The album name cannot exceed 255 characters.
• The album name cannot contain any of the following characters:
  . .. \ / : * ? " ' ` < > | { } [ ]
• The album name is case-insensitive.
• Duplicate album names are not allowed.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

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

Add assets to the album.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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 albumName: string = 'newAlbumName' + new Date().getTime();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
    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

Removes assets from the album.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';

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¹¹⁺

requestImage¹¹⁺

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

Requests an image.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
import image from '@ohos.multimedia.image'

class MediaHandler implements photoAccessHelper.MediaAssetDataHandler<image.ImageSource> {
    onDataPrepared(data: image.ImageSource) {
        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,
    sourceMode: photoAccessHelper.SourceMode.ORIGINAL_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>

Requests an image.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> {
    onDataPrepared(data: ArrayBuffer) {
        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,
    sourceMode: photoAccessHelper.SourceMode.ORIGINAL_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');
  });
}

MediaAssetDataHandler¹¹⁺

Media asset handler, which can be used to customize the media asset processing logic in onDataPrepared.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

onDataPrepared¹¹⁺

onDataPrepared(data: T): void

Called when the requested image is ready. T supports two data types: ArrayBuffer and ImageSource.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Example

import image from '@ohos.multimedia.image'

class MediaHandler implements photoAccessHelper.MediaAssetDataHandler<image.ImageSource> {
  onDataPrepared(data: image.ImageSource) {
    // Customize the processing logic for ImageSource.
    console.info('on image data prepared');
  }
}

class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> {
  onDataPrepared(data: ArrayBuffer) {
    // Customize the processing logic for ImageSource.
    console.info('on image data prepared');
  }
}

MemberType

Enumerates the member types.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

PhotoType

Enumerates media file types.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

AlbumType

Enumerates the album types.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

AlbumSubtype

Enumerate the album subtypes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

PhotoKeys

Defines the key information about an image or video file.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

AlbumKeys

Enumerates the key album attributes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

CreateOptions

Options for creating an image or video asset.

Note that the title cannot:

• Contain the filename extension.
• Exceed 255 characters.
• Contain any of the following characters:
  . .. \ / : * ? " ' ` < > | { } [ ]

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

FetchOptions

Defines the options for fetching media files.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

RequestOptions¹¹⁺

Represents request options.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

PhotoProxy¹¹⁺

Photo proxy object, which is used by the camera application to write image data.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

MediaChangeRequest¹¹⁺

Media change request, which is the parent class of the asset change request and album change request.

NOTE
MediaChangeRequest takes effect only after applyChanges is called.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

ResourceType¹¹⁺

Enumerates the types of the resources to write.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

ChangeData

Defines the return value of the listener callback.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

NotifyType

Enumerates the notification event types.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

DefaultChangeUri

Enumerates the DefaultChangeUri subtypes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

PhotoViewMIMETypes

Enumerates the media file types that can be selected.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

RecommendationType¹¹⁺

Enumerates the types of recommended images.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

RecommendationOptions¹¹⁺

Defines the image recommendation options. The image recommendation feature depends on the image data analysis capability, which varies with devices.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

PhotoSelectOptions

Defines the options for selecting images or videos.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

PhotoSelectResult

Defines information about the images or videos selected.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

DeliveryMode¹¹⁺

Enumerates the image delivery modes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core