@ohos.filemanagement.userFileManager (User Data Management)

The userFileManager module provides user data management capabilities, including accessing and modifying user media data (audio and video clips, images, and files).

NOTE

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

The APIs provided by this module are system APIs.

Modules to Import

import userFileManager from '@ohos.filemanagement.userFileManager';

userFileManager.getUserFileMgr

getUserFileMgr(context: Context): UserFileManager

Obtains a UserFileManager instance. This instance can be used to access and modify user media data (such as audio and video clips, images, and files).

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Context of the ability instance.

Return value

Type	Description
UserFileManager	UserFileManager instance obtained.

Example

// The userFileManager 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 mgr is not defined.
const context = getContext(this);
let mgr = userFileManager.getUserFileMgr(context);

UserFileManager

getPhotoAssets

getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the image and video assets.
callback	AsyncCallback<FetchResult<FileAsset>>	Yes	Callback invoked to return the image and video assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

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

  mgr.getPhotoAssets(fetchOptions, async (err, fetchResult) => {
    if (fetchResult != undefined) {
      console.info('fetchResult success');
      let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
      if (fileAsset != undefined) {
        console.info('fileAsset.displayName : ' + fileAsset.displayName);
      }
    } else {
      console.error('fetchResult fail' + err);
    }
  });
}

getPhotoAssets

getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the image and video assets.

Return value

Type	Description
Promise<FetchResult<FileAsset>>	Promise used to return the image and video assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

async function example() {
  console.info('getPhotoAssets');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    if (fetchResult != undefined) {
      console.info('fetchResult success');
      let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
      if (fileAsset != undefined) {
        console.info('fileAsset.displayName :' + fileAsset.displayName);
      }
    }
  } catch (err) {
    console.error('getPhotoAssets failed, message = ', err);
  }
}

createPhotoAsset

createPhotoAsset(displayName: string, albumUri: string, callback: AsyncCallback<FileAsset>): void;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the image or video to create.
albumUri	string	Yes	URI of the album where the image or video is located.
callback	AsyncCallback<FileAsset>	Yes	Callback invoked to return the image or video created.

Error codes

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

ID	Error Message
13900020	if type displayName or albumUri is not string.
14000001	if type displayName invalid.

Example

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

async function example() {
  console.info('createPhotoAssetDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };
  let albums: userFileManager.FetchResult<userFileManager.Album> = await mgr.getPhotoAlbums(fetchOptions);
  let album: userFileManager.Album = await albums.getFirstObject();
  let testFileName: string = 'testFile' + Date.now() + '.jpg';
  mgr.createPhotoAsset(testFileName, album.albumUri, (err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('createPhotoAsset file displayName' + fileAsset.displayName);
      console.info('createPhotoAsset successfully');
    } else {
      console.error('createPhotoAsset failed, message = ', err);
    }
  });
}

createPhotoAsset

createPhotoAsset(displayName: string, callback: AsyncCallback<FileAsset>): void;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the image or video to create.
callback	AsyncCallback<FileAsset>	Yes	Callback invoked to return the image or video created.

Error codes

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

ID	Error Message
13900020	if type displayName is not string.
14000001	if type displayName invalid.

Example

async function example() {
  console.info('createPhotoAssetDemo');
  let testFileName: string = 'testFile' + Date.now() + '.jpg';
  mgr.createPhotoAsset(testFileName, (err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('createPhotoAsset file displayName' + fileAsset.displayName);
      console.info('createPhotoAsset successfully');
    } else {
      console.error('createPhotoAsset failed, message = ', err);
    }
  });
}

createPhotoAsset

createPhotoAsset(displayName: string, albumUri?: string): Promise<FileAsset>;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the image or video to create.
albumUri	string	No	URI of the album where the image or video is located.

Return value

Type	Description
Promise<FileAsset>	Promise used to return the created image and video asset.

Error codes

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

ID	Error Message
13900020	if type displayName or albumUri is not string.

Example

async function example() {
  console.info('createPhotoAssetDemo');
  try {
    let testFileName: string = 'testFile' + Date.now() + '.jpg';
    let fileAsset: userFileManager.FileAsset = await mgr.createPhotoAsset(testFileName);
    console.info('createPhotoAsset file displayName' + fileAsset.displayName);
    console.info('createPhotoAsset successfully');
  } catch (err) {
    console.error('createPhotoAsset failed, message = ', err);
  }
}

createPhotoAsset

createPhotoAsset(displayName: string, createOption: PhotoCreateOptions, callback: AsyncCallback<FileAsset>): void;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the image or video to create.
createOption	PhotoCreateOptions	Yes	Options for creating an image or video asset.
callback	AsyncCallback<FileAsset>	Yes	Callback invoked to return the image or video created.

Error codes

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

ID	Error Message
13900020	if type displayName is not string.
14000001	if type displayName invalid.

Example

async function example() {
  console.info('createPhotoAssetDemo');
  let testFileName: string = 'testFile' + Date.now() + '.jpg';
  let createOption: userFileManager.PhotoCreateOptions = {
    subType: userFileManager.PhotoSubType.DEFAULT
  }
  mgr.createPhotoAsset(testFileName, createOption, (err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('createPhotoAsset file displayName' + fileAsset.displayName);
      console.info('createPhotoAsset successfully');
    } else {
      console.error('createPhotoAsset failed, message = ', err);
    }
  });
}

createPhotoAsset

createPhotoAsset(displayName: string, createOption: PhotoCreateOptions): Promise<FileAsset>;

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the image or video to create.
createOption	PhotoCreateOptions	Yes	Options for creating an image or video asset.

Return value

Type	Description
Promise<FileAsset>	Promise used to return the created image and video asset.

Error codes

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

ID	Error Message
13900020	if type displayName is not string.

Example

async function example() {
  console.info('createPhotoAssetDemo');
  try {
    let testFileName: string = 'testFile' + Date.now() + '.jpg';
    let createOption: userFileManager.PhotoCreateOptions = {
      subType: userFileManager.PhotoSubType.DEFAULT
    }
    let fileAsset: userFileManager.FileAsset = await mgr.createPhotoAsset(testFileName, createOption);
    console.info('createPhotoAsset file displayName' + fileAsset.displayName);
    console.info('createPhotoAsset successfully');
  } catch (err) {
    console.error('createPhotoAsset failed, message = ', err);
  }
}

createAudioAsset¹⁰⁺

createAudioAsset(displayName: string, callback: AsyncCallback<FileAsset>): void;

Creates an audio asset. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_AUDIO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the audio asset to create.
callback	AsyncCallback<FileAsset>	Yes	Callback invoked to return the created audio asset.

Error codes

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

ID	Error Message
13900020	if type displayName is not string.
14000001	if type displayName invalid.

Example

async function example() {
  console.info('createAudioAssetDemo');
  let testFileName: string = 'testFile' + Date.now() + '.mp3';
  mgr.createAudioAsset(testFileName, (err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('createAudioAsset file displayName' + fileAsset.displayName);
      console.info('createAudioAsset successfully');
    } else {
      console.error('createAudioAsset failed, message = ', err);
    }
  });
}

createAudioAsset¹⁰⁺

createAudioAsset(displayName: string): Promise<FileAsset>;

Creates an audio asset. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_AUDIO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the audio asset to create.

Return value

Type	Description
Promise<FileAsset>	Promise used to return the created audio asset.

Error codes

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

ID	Error Message
13900020	if type displayName is not string.

Example

async function example() {
  console.info('createAudioAssetDemo');
  try {
    let testFileName: string = 'testFile' + Date.now() + '.mp3';
    let fileAsset: userFileManager.FileAsset = await mgr.createAudioAsset(testFileName);
    console.info('createAudioAsset file displayName' + fileAsset.displayName);
    console.info('createAudioAsset successfully');
  } catch (err) {
    console.error('createAudioAsset failed, message = ', err);
  }
}

createAlbum¹⁰⁺

createAlbum(name: string, callback: AsyncCallback<Album>): void;

Creates an album. This API uses an asynchronous callback to return the result.

The album name must meet the following requirements:

The album name is a string of 1 to 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.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the album to create.
callback	AsyncCallback<Album>	Yes	Callback invoked to return the created album instance.

Example

async function example() {
  console.info('createAlbumDemo');
  let albumName: string = 'newAlbumName' + new Date().getTime();
  mgr.createAlbum(albumName, (err, album) => {
    if (err) {
      console.error('createAlbumCallback failed with err: ' + err);
      return;
    }
    console.info('createAlbumCallback successfully, album: ' + album.albumName + ' album uri: ' + album.albumUri);
  });
}

createAlbum¹⁰⁺

createAlbum(name: string): Promise<Album>;

Creates an album. This API uses a promise to return the result.

The album name must meet the following requirements:

The album name is a string of 1 to 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.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the album to create.

Return value

Type	Description
Promise<Album>	Promise used to return the created album instance.

Example

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

async function example() {
  console.info('createAlbumDemo');
  let albumName: string  = 'newAlbumName' + new Date().getTime();
  mgr.createAlbum(albumName).then((album) => {
    console.info('createAlbumPromise successfully, album: ' + album.albumName + ' album uri: ' + album.albumUri);
  }).catch((err: BusinessError) => {
    console.error('createAlbumPromise failed with err: ' + err);
  });
}

deleteAlbums¹⁰⁺

deleteAlbums(albums: Array<Album>, callback: AsyncCallback<void>): void;

Deletes albums. This API uses an asynchronous callback to return the result.

Ensure that the albums to be deleted exist. Only user albums can be deleted.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
albums	Array<Album>	Yes	Albums to delete.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  // Delete the album named newAlbumName.
  console.info('deleteAlbumsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo('album_name', 'newAlbumName');
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions);
  let album: userFileManager.Album = await fetchResult.getFirstObject();
  mgr.deleteAlbums([album], (err) => {
    if (err) {
      console.error('deletePhotoAlbumsCallback failed with err: ' + err);
      return;
    }
    console.info('deletePhotoAlbumsCallback successfully');
  });
  fetchResult.close();
}

deleteAlbums¹⁰⁺

deleteAlbums(albums: Array<Album>): Promise<void>;

Deletes albums. This API uses a promise to return the result.

Ensure that the albums to be deleted exist. Only user albums can be deleted.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
albums	Array<Album>	Yes	Albums to delete.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  // Delete the album named newAlbumName.
  console.info('deleteAlbumsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo('album_name', 'newAlbumName');
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions);
  let album: userFileManager.Album = await fetchResult.getFirstObject();
  mgr.deleteAlbums([album]).then(() => {
    console.info('deletePhotoAlbumsPromise successfully');
    }).catch((err: BusinessError) => {
      console.error('deletePhotoAlbumsPromise failed with err: ' + err);
  });
  fetchResult.close();
}

getAlbums¹⁰⁺

getAlbums(type: AlbumType, subType: AlbumSubType, options: FetchOptions, callback: AsyncCallback<FetchResult<Album>>): void;

Obtain 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.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
type	AlbumType	Yes	Type of the album to obtain.
subType	AlbumSubType	Yes	Subtype of the album.
options	FetchOptions	Yes	Options for fetching the albums.
callback	AsyncCallback<FetchResult<Album>>	Yes	Callback invoked to return the result.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOption.

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: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions, async (err, fetchResult) => {
    if (err) {
      console.error('getAlbumsCallback failed with err: ' + err);
      return;
    }
    if (fetchResult == undefined) {
      console.error('getAlbumsCallback fetchResult is undefined');
      return;
    }
    let album: userFileManager.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.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
type	AlbumType	Yes	Type of the album to obtain.
subType	AlbumSubType	Yes	Subtype of the album.
callback	AsyncCallback<FetchResult<Album>>	Yes	Callback invoked to return the result.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOption.

Example

async function example() {
  // Obtain the system album VIDEO, which is preset by default.
  console.info('getAlbumsDemo');
  mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.VIDEO, async (err, fetchResult) => {
    if (err) {
      console.error('getAlbumsCallback failed with err: ' + err);
      return;
    }
    if (fetchResult == undefined) {
      console.error('getAlbumsCallback fetchResult is undefined');
      return;
    }
    let album: userFileManager.Album = await fetchResult.getFirstObject();
    console.info('getAlbumsCallback successfully, albumUri: ' + album.albumUri);
    fetchResult.close();
  });
}

getAlbums¹⁰⁺

getAlbums(type: AlbumType, subType: AlbumSubType, options?: FetchOptions): Promise<FetchResult<Album>>;

Obtain 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.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
type	AlbumType	Yes	Type of the album to obtain.
subType	AlbumSubType	Yes	Subtype of the album.
options	FetchOptions	No	Options for fetching the albums. If this parameter is not specified, the albums are obtained based on the album type by default.

Return value

Type	Description
Promise<FetchResult<Album>>	Promise used to return the result.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOption.

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: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions).then( async (fetchResult) => {
    if (fetchResult == undefined) {
      console.error('getAlbumsPromise fetchResult is undefined');
      return;
    }
    let album: userFileManager.Album = await fetchResult.getFirstObject();
    console.info('getAlbumsPromise successfully, albumName: ' + album.albumName);
    fetchResult.close();
  }).catch((err: BusinessError) => {
    console.error('getAlbumsPromise failed with err: ' + err);
  });
}

getPhotoAlbums

getPhotoAlbums(options: AlbumFetchOptions, callback: AsyncCallback<FetchResult<Album>>): void;

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

This API will be deprecated. Use getAlbums¹⁰⁺ instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
options	AlbumFetchOptions	Yes	Options for fetching the albums.
callback	AsyncCallback<FetchResult<Album>>	Yes	Callback invoked to return the image and video albums obtained.

Error codes

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

ID	Error Message
13900020	if type options is not AlbumFetchOptions.

Example

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

async function example() {
  console.info('getPhotoAlbumsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };

  mgr.getPhotoAlbums(albumFetchOptions, (err, fetchResult) => {
    if (fetchResult != undefined) {
      console.info('albums.count = ' + fetchResult.getCount());
      fetchResult.getFirstObject((err, album) => {
        if (album != undefined) {
          console.info('first album.albumName = ' + album.albumName);
        } else {
          console.error('album is undefined, err = ', err);
        }
      });
    } else {
      console.error('getPhotoAlbums fail, message = ', err);
    }
  });
}

getPhotoAlbums

getPhotoAlbums(options: AlbumFetchOptions): Promise<FetchResult<Album>>;

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

This API will be deprecated. Use getAlbums¹⁰⁺ instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
options	AlbumFetchOptions	Yes	Options for fetching the albums.

Return value

Type	Description
Promise<FetchResult<Album>>	Promise used to return the image and video albums obtained.

Error codes

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

ID	Error Message
13900020	if type options is not AlbumFetchOptions.

Example

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

async function example() {
  console.info('getPhotoAlbumsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };
  try {
    let fetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getPhotoAlbums(albumFetchOptions);
    console.info('album.count = ' + fetchResult.getCount());
    const album: userFileManager.Album = await fetchResult.getFirstObject();
    console.info('first album.albumName = ' + album.albumName);
  } catch (err) {
    console.error('getPhotoAlbums fail, message = ' + err);
  }
}

getPrivateAlbum

getPrivateAlbum(type: PrivateAlbumType, callback: AsyncCallback<FetchResult<PrivateAlbum>>): void;

Obtains the system album. This API uses an asynchronous callback to return the result.

This API will be deprecated. Use getAlbums¹⁰⁺ instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
type	PrivateAlbumType	Yes	Type of the system album to obtain.
callback	AsyncCallback<FetchResult<PrivateAlbum>>	Yes	Callback invoked to return the album obtained.

Error codes

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

ID	Error Message
13900020	if type type is not PrivateAlbumType.

Example

async function example() {
  console.info('getPrivateAlbumDemo');
  mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH, async (err, fetchResult) => {
    if (fetchResult != undefined) {
      let trashAlbum: userFileManager.PrivateAlbum = await fetchResult.getFirstObject();
      console.info('first album.albumName = ' + trashAlbum.albumName);
    } else {
      console.error('getPrivateAlbum failed. message = ', err);
    }
  });
}

getPrivateAlbum

getPrivateAlbum(type: PrivateAlbumType): Promise<FetchResult<PrivateAlbum>>;

Obtains the system album. This API uses a promise to return the result.

This API will be deprecated. Use getAlbums¹⁰⁺ instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
type	PrivateAlbumType	Yes	Type of the system album to obtain.

Return value

Type	Description
Promise<FetchResult<PrivateAlbum>>	Promise used to return the system album obtained.

Error codes

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

ID	Error Message
13900020	if type type is not PrivateAlbumType.

Example

async function example() {
  console.info('getPrivateAlbumDemo');
  try {
    let fetchResult: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
    let trashAlbum: userFileManager.PrivateAlbum = await fetchResult.getFirstObject();
    console.info('first album.albumName = ' + trashAlbum.albumName);
  } catch (err) {
    console.error('getPrivateAlbum failed. message = ', err);
  }
}

getAudioAssets

getAudioAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;

Obtains audio assets. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_AUDIO

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the audio assets.
callback	AsyncCallback<FetchResult<FileAsset>>	Yes	Callback invoked to return the audio assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

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

  mgr.getAudioAssets(fetchOptions, async (err, fetchResult) => {
    if (fetchResult != undefined) {
      console.info('fetchFileResult success');
      let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
      if (fileAsset != undefined) {
        console.info('fileAsset.displayName :' + fileAsset.displayName);
      }
    } else {
      console.error('fetchFileResult fail' + err);
    }
  });
}

getAudioAssets

getAudioAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;

Obtains audio assets. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Required permissions: ohos.permission.READ_AUDIO

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the audio assets.

Return value

Type	Description
Promise<FetchResult<FileAsset>>	Promise used to return the audio assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

async function example() {
  console.info('getAudioAssets');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getAudioAssets(fetchOptions);
    if (fetchResult != undefined) {
      console.info('fetchFileResult success');
      let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
      if (fileAsset != undefined) {
        console.info('fileAsset.displayName :' + fileAsset.displayName);
      }
    }
  } catch (err) {
    console.error('getAudioAssets failed, message = ', err);
  }
}

delete

delete(uri: string, callback: AsyncCallback<void>): void;

Deletes a media file. This API uses an asynchronous callback to return the result. The deleted file is moved to the recycle bin.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the media file.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Error codes

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

ID	Error Message
13900020	if type uri is not string.

Example

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

async function example() {
  console.info('deleteAssetDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    const fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();


    if (asset == undefined) {
      console.error('asset not exist');
      return;
    }
    mgr.delete(asset.uri, (err) => {
      if (err == undefined) {
        console.info('delete successfully');
      } else {
        console.error('delete failed with error: ' + err);
      }
    });
  } catch (err) {
    console.info('fetch failed, message =', err);
  }
}

delete

delete(uri: string): Promise<void>;

Deletes a media file. This API uses a promise to return the result. The deleted file is moved to the recycle bin.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the media file.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
13900020	if type uri is not string.

Example

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

async function example() {
  console.info('deleteDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    const fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    if (asset == undefined) {
      console.error('asset not exist');
      return;
    }
    await mgr.delete(asset.uri);
    console.info('delete successfully');
  } catch (err) {
    console.error('delete failed with error: ' + err);
  }
}

getActivePeers

getActivePeers(callback: AsyncCallback<Array<PeerInfo>>): void;

Obtains information about online peer devices. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.DistributedCore

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<PeerInfo>>	Yes	Callback invoked to return a list of online peer devices.

Example

async function example() {
  console.info('getActivePeersDemo');
  mgr.getActivePeers((err, devicesInfo) => {
    if (devicesInfo != undefined) {
      console.log('getActivePeers succeed.');
      for (let i = 0; i < devicesInfo.length; i++) {
        console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
      }
    } else {
      console.error('getActivePeers failed. message = ', err);
    }
  });
}

getActivePeers

getActivePeers(): Promise<Array<PeerInfo>>;

Obtains information about online peer devices. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.DistributedCore

Return value

Type	Description
Promise<Array<PeerInfo>>	Promise used to return a list of online peer devices.

Example

async function example() {
  console.info('getActivePeersDemo');
  try {
    let devicesInfo: Array<userFileManager.PeerInfo> = await mgr.getActivePeers();
    if (devicesInfo != undefined) {
      console.log('getActivePeers succeed.');
      for (let i = 0; i < devicesInfo.length; i++) {
        console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
      }
    } else {
      console.error('get distributed fail');
    }
  } catch (err) {
    console.error('getActivePeers failed. message = ', err);
  }
}

getAllPeers

getAllPeers(callback: AsyncCallback<Array<PeerInfo>>): void;

Obtains information about all peer devices. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.DistributedCore

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<PeerInfo>>	Yes	Callback invoked to return the peer device information obtained.

Example

async function example() {
  console.info('getAllPeersDemo');
  mgr.getAllPeers((err, devicesInfo) => {
    if (devicesInfo != undefined) {
      console.log('getAllPeers succeed.');
      for (let i = 0; i < devicesInfo.length; i++) {
        console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
      }
    } else {
      console.error('getAllPeers failed. message = ', err);
    }
  });
}

getAllPeers

getAllPeers(): Promise<Array<PeerInfo>>;

Obtains information about all peer devices. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.UserFileManager.DistributedCore

Return value

Type	Description
Promise<Array<PeerInfo>>	Promise used to return the information obtained.

Example

async function example() {
  console.info('getAllPeersDemo');
  try {
    let devicesInfo: Array<userFileManager.PeerInfo> = await mgr.getAllPeers();

    if (devicesInfo != undefined) {
      console.log('getAllPeers succeed.');
      for (let i = 0; i < devicesInfo.length; i++) {
        console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
      }
    } else {
      console.error('get distributed fail');
    }
  } catch (err) {
    console.error('getAllPeers failed. message = ', err);
  }
}

getPhotoIndex¹⁰⁺

getPhotoIndex(photoUri: string, albumUri: string, options: FetchOptions, callback: AsyncCallback<number>): void

Obtains the index of an image or video in an album. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
photoUri	string	Yes	URI of the media asset whose index is to be obtained.
albumUri	string	Yes	Album URI, which can be an empty string. If it is an empty string, all the media assets in the Gallery are obtained by default.
options	FetchOptions	Yes	Fetch options. Only one search condition or sorting mode must be set in predicates. If no value is set or multiple search conditions or sorting modes are set, the API cannot be called successfully.

Return value

Type	Description
AsyncCallback<number>	Callback invoked to return the index obtained.

Error codes

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

ID	Error Message
401	if parameter is invalid.

Example

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

async function example() {
  try {
    console.info('getPhotoIndexDemo');
    let predicatesForGetAsset: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOp: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicatesForGetAsset
    };
    // Obtain the uri of the album
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.FAVORITE, fetchOp);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    predicates.orderByAsc(userFileManager.ImageVideoKey.DATE_MODIFIED.toString());
    let fetchOptions: userFileManager.FetchOptions = {
      fetchColumns: [userFileManager.ImageVideoKey.DATE_MODIFIED.toString()],
      predicates: predicates
    };
    let photoFetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOptions);
    let expectIndex = 1;
    // Obtain the uri of the second file
    let photoAsset: userFileManager.FileAsset = await photoFetchResult.getPositionObject(expectIndex);
    mgr.getPhotoIndex(photoAsset.uri, album.albumUri, fetchOptions, (err, index) => {
      if (err == undefined) {
        console.info(`getPhotoIndex successfully and index is : ${index}`);
      } else {
        console.info(`getPhotoIndex failed;`);
      }
    });
  } catch (error) {
    console.info(`getPhotoIndex failed; error: ${error}`);
  }
}

getPhotoIndex¹⁰⁺

getPhotoIndex(photoUri: string, albumUri: string, options: FetchOptions): Promise<number>

Obtains the index of an image or video in an album. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
photoUri	string	Yes	URI of the media asset whose index is to be obtained.
albumUri	string	Yes	Album URI, which can be an empty string. If it is an empty string, all the media assets in the Gallery are obtained by default.
options	FetchOptions	Yes	Fetch options. Only one search condition or sorting mode must be set in predicates. If no value is set or multiple search conditions or sorting modes are set, the API cannot be called successfully.

Return value

Type	Description
Promise<number>	Promise used to return the index obtained.

Error codes

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

ID	Error Message
401	if parameter is invalid.

Example

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

async function example() {
  try {
    console.info('getPhotoIndexDemo');
    let predicatesForGetAsset: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOp: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicatesForGetAsset
    };
    // Obtain the uri of the album
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.FAVORITE, fetchOp);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    predicates.orderByAsc(userFileManager.ImageVideoKey.DATE_MODIFIED.toString());
    let fetchOptions: userFileManager.FetchOptions = {
      fetchColumns: [userFileManager.ImageVideoKey.DATE_MODIFIED.toString()],
      predicates: predicates
    };
    let photoFetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOptions);
    let expectIndex = 1;
    // Obtain the uri of the second file
    let photoAsset: userFileManager.FileAsset = await photoFetchResult.getPositionObject(expectIndex);
    mgr.getPhotoIndex(photoAsset.uri, album.albumUri, fetchOptions).then((index) => {
      console.info(`getPhotoIndex successfully and index is : ${index}`);
    }).catch((err: BusinessError) => {
      console.info(`getPhotoIndex failed; error: ${err}`);
    });
  } catch (error) {
    console.info(`getPhotoIndex failed; error: ${error}`);
  }
}

release

release(callback: AsyncCallback<void>): void

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback invoked to return the result.

Example

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

release

release(): Promise<void>

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

async function example() {
  console.info('releaseDemo');
  try {
    await mgr.release();
    console.info('release ok.');
  } catch (err) {
    console.error('release failed. message = ', err);
  }
}

on¹⁰⁺

on(uri: string, forSubUri: boolean, callback: Callback<ChangeData>) : void

Registers a listener for the specified URI.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the file asset or album, or DefaultChangeUri.
forSubUri	boolean	Yes	Whether to perform fuzzy listening. If uri is the URI of an album, the value true means to listen for the changes of the files in the album; the value false means to listen for the changes of the album. If uri is the URI of a file asset, there is no difference between true and false for forSubUri. If uri is DefaultChangeUri, forSubUri must be set to true. If forSubUri is false, the URI cannot be found and no message can be received.
callback	Callback<ChangeData>	Yes	Callback invoked to return ChangeData. NOTE: Different callbacks can be registered for a URI. You can use off¹⁰⁺ to disable the specified callback or all callbacks for the URI.

Error codes

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

ID	Error Message
13900020	if parameter is invalid.

Example

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

async function example() {
  console.info('onDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  if (fileAsset != undefined) {
    console.info('fileAsset.displayName : ' + fileAsset.displayName);
  }
  let onCallback1 = (changeData: userFileManager.ChangeData) => {
      console.info('onCallback1 success, changData: ' + JSON.stringify(changeData));
    //file had changed, do something
  }
  let onCallback2 = (changeData: userFileManager.ChangeData) => {
      console.info('onCallback2 success, changData: ' + JSON.stringify(changeData));
    // File changed. Do something.
  }
  // Register onCallback1.
  mgr.on(fileAsset.uri, false, onCallback1);
  // Register onCallback2.
  mgr.on(fileAsset.uri, false, onCallback2);

  fileAsset.favorite(true, (err) => {
    if (err == undefined) {
      console.info('favorite successfully');
    } else {
      console.error('favorite failed with error:' + err);
    }
  });
}

off¹⁰⁺

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

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the file asset or album, or DefaultChangeUri.
callback	Callback<ChangeData>	No	Callback registered by on¹⁰⁺. If this parameter is not specified, all listener callbacks registered for the URI will be unregistered. NOTE: The specified callback will not be invoked.

Error codes

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

ID	Error Message
13900020	if parameter is invalid.

Example

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

async function example() {
  console.info('offDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  if (fileAsset != undefined) {
    console.info('fileAsset.displayName : ' + fileAsset.displayName);
  }
  let onCallback1 = (changeData: userFileManager.ChangeData) => {
    console.info('onCallback1 on');
  }
  let onCallback2 = (changeData: userFileManager.ChangeData) => {
    console.info('onCallback2 on');
  }
  // Register onCallback1.
  mgr.on(fileAsset.uri, false, onCallback1);
  // Register onCallback2.
  mgr.on(fileAsset.uri, false, onCallback2);
  // Disable the listening of onCallback1.
  mgr.off(fileAsset.uri, onCallback1);
  fileAsset.favorite(true, (err) => {
    if (err == undefined) {
      console.info('favorite successfully');
    } else {
      console.error('favorite failed with error:' + err);
    }
  });
}

on

on(type: ChangeEvent, callback: Callback<void>): void

Subscribes to changes of the file management library. This API uses a callback to return the result.

This API will be deprecated. Use on¹⁰⁺ instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
type	ChangeEvent	Yes	Type of event to subscribe to. deviceChange indicates the device change. albumChange indicates the album change. imageChange indicates the image change. audioChange indicates the audio file change. videoChange indicates the video file change. remoteFileChange indicates the file change on the registered device.
callback	Callback<void>	Yes	Callback that returns no value.

Example

async function example() {
  console.info('onDemo');
  let count = 0;
  mgr.on('imageChange', () => {
    count++;
    // Image file changed. Do something.
  });
  try {
    let testFileName: string = 'testFile' + Date.now() + '.jpg';
    let fileAsset: userFileManager.FileAsset = await mgr.createPhotoAsset(testFileName);
    console.info('createPhotoAsset file displayName' + fileAsset.displayName);
    console.info('createPhotoAsset successfully');
  } catch (err) {
    console.error('createPhotoAsset failed, message = ' + err);
  }
  // Sleep 1s.
  if (count > 0) {
    console.info('onDemo success');
  } else {
    console.error('onDemo fail');
  }
  mgr.off('imageChange', () => {
    // Unsubscription succeeds.
  });
}

off

off(type: ChangeEvent, callback?: Callback<void>): void

Unsubscribes from changes of the file management library. This API uses a callback to return the result.

This API will be deprecated. Use off¹⁰⁺ instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
type	ChangeEvent	Yes	Type of event to subscribe to. deviceChange indicates the device change. albumChange indicates the album change. imageChange indicates the image change. audioChange indicates the audio file change. videoChange indicates the video file change. remoteFileChange indicates the change of the file on a registered device.
callback	Callback<void>	No	Callback that returns no value.

Example

async function example() {
  console.info('offDemo');
  let count = 0;
  mgr.on('imageChange', () => {
    count++;
    // Image file changed. Do something.
  });

  mgr.off('imageChange', () => {
    // Unsubscription succeeds.
  });

  try {
    let testFileName: string = 'testFile' + Date.now() + '.jpg';
    let fileAsset: userFileManager.FileAsset = await mgr.createPhotoAsset(testFileName);
    console.info('createPhotoAsset file displayName' + fileAsset.displayName);
    console.info('createPhotoAsset successfully');
  } catch (err) {
    console.error('createPhotoAsset failed, message = ' + err);
  }
  // Sleep 1s.
  if (count == 0) {
    console.info('offDemo success');
  } else {
    console.error('offDemo fail');
  }
}

FileAsset

Provides APIs for encapsulating file asset attributes.

Attributes

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
uri	string	Yes	No	Media asset URI, for example, file://media/Photo/1/IMG_datetime_0001/displayName.jpg. For details, see Media File URI.
fileType	FileType	Yes	No	Type of the file.
displayName	string	Yes	Yes	File name, including the file name extension, to display.

get

get(member: string): MemberType;

Obtains the value of a FileAsset parameter.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
member	string	Yes	Name of the parameter, for example, ImageVideoKey.DISPLAY_NAME. You need to enter the PhotoKeys to be obtained in fetchColumns for all attributes except uri, photoType, and displayName. For example, fetchColumns: ['title'].

Example

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

async function example() {
  console.info('fileAssetGetDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: ['title'],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    let title: userFileManager.ImageVideoKey = userFileManager.ImageVideoKey.TITLE;
    let fileAssetTitle: userFileManager.MemberType = fileAsset.get(title.toString());
    console.info('fileAsset Get fileAssetTitle = ', fileAssetTitle);
  } catch (err) {
    console.error('release failed. message = ', err);
  }
}

set

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

Sets a FileAsset parameter.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
member	string	Yes	Name of the parameter, for example, ImageVideoKey.DISPLAY_NAME.
value	string	Yes	Value to set. Only the values of DISPLAY_NAME and TITLE can be changed.

Example

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

async function example() {
  console.info('fileAssetSetDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    let displayName: string = userFileManager.ImageVideoKey.DISPLAY_NAME.toString();
    fileAsset.set(displayName, 'newDisplayName1');
  } catch (err) {
    console.error('release failed. message = ', err);
  }
}

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 or ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  console.info('commitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  let displayName: string = userFileManager.ImageVideoKey.DISPLAY_NAME.toString();
  let fileAssetDisplayName: userFileManager.MemberType = fileAsset.get(displayName);
  console.info('fileAsset get fileAssetDisplayName = ', fileAssetDisplayName);
  let newFileAssetDisplayName = 'new' + fileAssetDisplayName;
  console.info('fileAsset newFileAssetDisplayName = ', newFileAssetDisplayName);
  fileAsset.set(displayName, newFileAssetDisplayName);
  fileAsset.commitModify((err) => {
    if (err == undefined) {
      let commitModifyDisplayName = fileAsset.get(displayName);
      console.info('fileAsset commitModify successfully, commitModifyDisplayName = ', commitModifyDisplayName);
    } else {
      console.error('commitModify failed, message =', err);
    }
  });
}

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 or ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  console.info('commitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  let displayName = userFileManager.ImageVideoKey.DISPLAY_NAME.toString();
  let fileAssetDisplayName: userFileManager.MemberType = fileAsset.get(displayName);
  console.info('fileAsset get fileAssetDisplayName = ', fileAssetDisplayName);
  let newFileAssetDisplayName = 'new' + fileAssetDisplayName;
  console.info('fileAsset newFileAssetDisplayName = ', newFileAssetDisplayName);
  fileAsset.set(displayName, newFileAssetDisplayName);
  try {
    await fileAsset.commitModify();
    let commitModifyDisplayName = fileAsset.get(displayName);
    console.info('fileAsset commitModify successfully, commitModifyDisplayName = ', commitModifyDisplayName);
  } catch (err) {
    console.error('commitModify failed. message = ', err);
  }
}

open

open(mode: string, callback: AsyncCallback<number>): void

Opens this file asset. This API uses an asynchronous callback to return the result.

NOTE
The write operations are mutually exclusive. After a write operation is complete, you must call close to release the resource.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.READ_AUDIO, ohos.permission.WRITE_IMAGEVIDEO, or ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
mode	string	Yes	File open mode, which can be r (read-only), w (write-only), or rw (read-write).
callback	AsyncCallback<number>	Yes	Callback invoked to return the file descriptor of the file opened.

Example

async function example() {
  console.info('openDemo');
   let testFileName: string = 'testFile' + Date.now() + '.jpg';
  const fileAsset: userFileManager.FileAsset = await mgr.createPhotoAsset(testFileName);
  fileAsset.open('rw', (err, fd) => {
    if (fd != undefined) {
      console.info('File fd' + fd);
      fileAsset.close(fd);
    } else {
      console.error('File err' + err);
    }
  });
}

open

open(mode: string): Promise<number>

Opens this file asset. This API uses a promise to return the result.

NOTE
The write operations are mutually exclusive. After a write operation is complete, you must call close to release the resource.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.READ_AUDIO, ohos.permission.WRITE_IMAGEVIDEO, or ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
mode	string	Yes	File open mode, which can be r (read-only), w (write-only), or rw (read-write).

Return value

Type	Description
Promise<number>	Promise used to return the file descriptor of the file opened.

Example

async function example() {
  console.info('openDemo');
  try {
    let testFileName: string = 'testFile' + Date.now() + '.jpg';
    const fileAsset: userFileManager.FileAsset = await mgr.createPhotoAsset(testFileName);
    let fd: number = await fileAsset.open('rw');
    if (fd != undefined) {
      console.info('File fd' + fd);
      fileAsset.close(fd);
    } else {
      console.error(' open File fail');
    }
  } catch (err) {
    console.error('open Demo err' + err);
  }
}

close

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

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
fd	number	Yes	File descriptor of the file to close.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  console.info('closeDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    const fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    let fd: number = await fileAsset.open('rw');
    console.info('file fd', fd);
    fileAsset.close(fd, (err) => {
      if (err == undefined) {
        console.info('asset close succeed.');
      } else {
        console.error('close failed, message = ' + err);
      }
    });
  } catch (err) {
    console.error('close failed, message = ' + err);
  }
}

close

close(fd: number): Promise<void>

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
fd	number	Yes	File descriptor of the file to close.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  console.info('closeDemo');
  try {
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    const asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    let fd: number = await asset.open('rw');
    console.info('file fd', fd);
    await asset.close(fd);
    console.info('asset close succeed.');
  } catch (err) {
    console.error('close failed, message = ' + err);
  }
}

getThumbnail

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

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

Required permissions: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<image.PixelMap>	Yes	Callback invoked to return the PixelMap of the thumbnail.

Example

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

async function example() {
  console.info('getThumbnailDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let asset: userFileManager.FileAsset = 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', err);
    }
  });
}

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 or ohos.permission.READ_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
size	image.Size	Yes	Size of the thumbnail.
callback	AsyncCallback<image.PixelMap>	Yes	Callback invoked to return the PixelMap of the thumbnail.

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: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let size: image.Size = { width: 720, height: 720 };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const asset: userFileManager.FileAsset = 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', err);
    }
  });
}

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 or ohos.permission.READ_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
size	image.Size	No	Size of the thumbnail.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the PixelMap of the thumbnail.

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: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let size: image.Size = { width: 720, height: 720 };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const asset: userFileManager.FileAsset = 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' + err);
  });
}

favorite

favorite(isFavorite: boolean, callback: AsyncCallback<void>): void

Favorites or unfavorites this file asset. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
isFavorite	boolean	Yes	Operation to perform. The value true means to favorite the file asset, and false means the opposite.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  console.info('favoriteDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  asset.favorite(true, (err) => {
    if (err == undefined) {
      console.info('favorite successfully');
    } else {
      console.error('favorite failed with error:' + err);
    }
  });
}

favorite

favorite(isFavorite: boolean): Promise<void>

Favorites or unfavorites this file asset. This API uses a promise to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
isFavorite	boolean	Yes	Operation to perform. The value true means to favorite the file asset, and false means the opposite.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  console.info('favoriteDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  asset.favorite(true).then(() => {
    console.info('favorite successfully');
  }).catch((err: BusinessError) => {
    console.error('favorite failed with error:' + err);
  });
}

setHidden¹⁰⁺

setHidden(hiddenState: boolean, callback: AsyncCallback<void>): void

Sets this file asset to hidden state. This API uses an asynchronous callback to return the result.

The private files set to hidden state are located in the private album (in hidden state) and are not open to third-party applications. After obtaining private files from the private album, users can set hiddenState to false to remove them from the private album.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
hiddenState	boolean	Yes	Whether to set a file to hidden state. The value true means to hide the file; the value false means the opposite.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Error codes

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

ID	Error Message
202	Called by non-system application.
13900020	if parameter is invalid.

Example

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

async function example() {
  console.info('setHiddenDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  asset.setHidden(true, (err) => {
    if (err == undefined) {
      console.info('setHidden successfully');
    } else {
      console.error('setHidden failed with error:' + err);
    }
  });
}

setHidden¹⁰⁺

setHidden(hiddenState: boolean): Promise<void>

Sets this file asset to hidden state. This API uses a promise to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
hiddenState	boolean	Yes	Whether to set a file to hidden state. The value true means to hide the file; the value false means the opposite.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
202	Called by non-system application.
13900020	if parameter is invalid.

Example

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

async function example() {
  // Restore a file from a hidden album. Before the operation, ensure that the file exists in the hidden album.
  console.info('setHiddenDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let albumList: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.HIDDEN);
  const album: userFileManager.Album = await albumList.getFirstObject();
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
  const asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  asset.setHidden(false).then(() => {
    console.info('setHidden successfully');
  }).catch((err: BusinessError) => {
    console.error('setHidden failed with error:' + err);
  });
}

getExif¹⁰⁺

getExif(): Promise<string>

Obtains a JSON string consisting of the exchangeable image file format (EXIF) tags of this JPG image. This API uses a promise to return the result.

CAUTION
This API returns a JSON string consisting of EXIF tags. The complete EXIF information consists of all_exif and ImageVideoKey.USER_COMMENT. These two fields must be passed in via fetchColumns.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Return value

Type	Description
Promise<string>	Promise used to return the JSON string obtained.

Supported EXIF tags

For details about the EXIF tags, see image.PropertyKey.

Key Value	Description
BitsPerSample	Number of bits per pixel.
Orientation	Image orientation.
ImageLength	Image length.
ImageWidth	Image width.
GPSLatitude	GPS latitude of the image.
GPSLongitude	GPS longitude of the image.
GPSLatitudeRef	Longitude reference, for example, W or E.
GPSLongitudeRef	Latitude reference, for example, N or S.
DateTimeOriginal	Shooting time.
ExposureTime	Exposure time.
SceneType	Shooting scene type.
ISOSpeedRatings	ISO sensitivity or speed.
FNumber	f-number.
DateTime	Date and time when the image was last modified.
GPSTimeStamp	GPS timestamp.
GPSDateStamp	GPS date stamp.
ImageDescription	Image description.
Make	Camera vendor.
Model	Model.
PhotoMode	Photo mode.
SensitivityType	Sensitivity type.
StandardOutputSensitivity	Standard output sensitivity.
RecommendedExposureIndex	Recommended exposure index.
ApertureValue	Aperture value.
MeteringMode	Metering mode.
LightSource	Light source.
Flash	Flash status.
FocalLength	Focal length.
UserComment	User comment.
PixelXDimension	Pixel X dimension.
PixelYDimension	Pixel Y dimension.
WhiteBalance	White balance.
FocalLengthIn35mmFilm	Focal length in 35 mm film.
ExposureBiasValue	Exposure compensation.

Example

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

async function example() {
  try {
    console.info('getExifDemo');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    predicates.isNotNull('all_exif')
    let fetchOptions: userFileManager.FetchOptions = {
      fetchColumns: ['all_exif', userFileManager.ImageVideoKey.USER_COMMENT.toString()],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    console.info('getExifDemo fileAsset displayName: ' + JSON.stringify(fileAsset.displayName));
    let exifMessage: string = await fileAsset.getExif();
    let userCommentKey: string = 'UserComment';
    let userComment: string = JSON.stringify(JSON.parse(exifMessage), [userCommentKey]);
    console.info('getExifDemo userComment: ' + JSON.stringify(userComment));
    fetchResult.close();
  } catch (err) {
    console.error('getExifDemoCallback failed with error: ' + err);
  }
}

getExif¹⁰⁺

getExif(callback: AsyncCallback<string>): void

Obtains a JSON string consisting of the EXIF tags of this JPG image. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<string>	Yes	Callback invoked to return the JSON string obtained.

Supported EXIF tags

For details about the EXIF tags, see image.PropertyKey.

Key Value	Description
BitsPerSample	Number of bits per pixel.
Orientation	Image orientation.
ImageLength	Image length.
ImageWidth	Image width.
GPSLatitude	GPS latitude of the image.
GPSLongitude	GPS longitude of the image.
GPSLatitudeRef	Longitude reference, for example, W or E.
GPSLongitudeRef	Latitude reference, for example, N or S.
DateTimeOriginal	Shooting time.
ExposureTime	Exposure time.
SceneType	Shooting scene type.
ISOSpeedRatings	ISO sensitivity or speed.
FNumber	f-number.
DateTime	Date and time when the image was last modified.
GPSTimeStamp	GPS timestamp.
GPSDateStamp	GPS date stamp.
ImageDescription	Image description.
Make	Camera vendor.
Model	Model.
PhotoMode	Photo mode.
SensitivityType	Sensitivity type.
StandardOutputSensitivity	Standard output sensitivity.
RecommendedExposureIndex	Recommended exposure index.
ApertureValue	Aperture value.
MeteringMode	Metering mode.
LightSource	Light source.
Flash	Flash status.
FocalLength	Focal length.
UserComment	User comment.
PixelXDimension	Pixel X dimension.
PixelYDimension	Pixel Y dimension.
WhiteBalance	White balance.
FocalLengthIn35mmFilm	Focal length in 35 mm film.
ExposureBiasValue	Exposure compensation.

Example

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

async function example() {
  try {
    console.info('getExifDemo');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    predicates.isNotNull('all_exif')
    let fetchOptions: userFileManager.FetchOptions = {
      fetchColumns: ['all_exif', userFileManager.ImageVideoKey.USER_COMMENT.toString()],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    console.info('getExifDemo fileAsset displayName: ' + JSON.stringify(fileAsset.displayName));
    let userCommentKey: string = 'UserComment';
    fileAsset.getExif((err, exifMessage) => {
      if (exifMessage != undefined) {
        let userComment: string = JSON.stringify(JSON.parse(exifMessage), [userCommentKey]);
        console.info('getExifDemo userComment: ' + JSON.stringify(userComment));
      } else {
        console.error('getExif failed, message = ', err);
      }
    });
    fetchResult.close();
  } catch (err) {
    console.error('getExifDemoCallback failed with error: ' + err);
  }
}

setUserComment¹⁰⁺

setUserComment(userComment: string): Promise<void>

Sets user comment information of an image or video. This API uses a promise to return the result.

NOTE
This API can be used to modify the comment information of only images or videos.

System API: This is a system API.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
userComment	string	Yes	User comment information to set, which cannot exceed 140 characters.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  try {
    console.info('setUserCommentDemo')
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOptions: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    let userComment: string = 'test_set_user_comment';
    await fileAsset.setUserComment(userComment);
  } catch (err) {
    console.error('setUserCommentDemoCallback failed with error: ' + err);
  }
}

setUserComment¹⁰⁺

setUserComment(userComment: string, callback: AsyncCallback<void>): void

Sets user comment information of an image or video. This API uses an asynchronous callback to return the result.

NOTE
This API can be used to modify the comment information of only images or videos.

System API: This is a system API.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
userComment	string	Yes	User comment information to set, which cannot exceed 140 characters.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  try {
    console.info('setUserCommentDemo')
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOptions: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOptions);
    let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    let userComment: string = 'test_set_user_comment';
    fileAsset.setUserComment(userComment, (err) => {
      if (err === undefined) {
        console.info('setUserComment successfully');
      } else {
        console.error('setUserComment failed with error: ' + err);
      }
    });
  } catch (err) {
    console.error('setUserCommentDemoCallback failed with error: ' + err);
  }
}

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.UserFileManager.Core

Return value

Type	Description
number	Returns the total number of files obtained.

Example

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

async function example() {
  console.info('getCountDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const fetchCount: number = 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.UserFileManager.Core

Return value

Type	Description
boolean	Returns true if the cursor is in the last row of the result set; returns false otherwise.

Example

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

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  const fetchCount: number = fetchResult.getCount();
  console.info('count:' + fetchCount);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getLastObject();
  if (fetchResult.isAfterLast()) {
    console.info('fileAsset isAfterLast displayName = ', fileAsset.displayName);
  } else {
    console.info('fileAsset  not isAfterLast ');
  }
}

close

close(): void

Releases and invalidates this FetchFileResult instance. After this instance is released, the APIs in this instance cannot be invoked.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Example

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

async function example() {
  console.info('fetchResultCloseDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    fetchResult.close();
    console.info('close succeed.');
  } catch (err) {
    console.error('close fail. message = ' + err);
  }
}

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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<T>	Yes	Callback invoked to return the first file asset.

Example

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

async function example() {
  console.info('getFirstObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  fetchResult.getFirstObject((err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('fileAsset displayName: ', fileAsset.displayName);
    } else {
      console.error('fileAsset failed with err:' + err);
    }
  });
}

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.UserFileManager.Core

Return value

Type	Description
Promise<T>	Promise used to return the first object in the result set.

Example

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

async function example() {
  console.info('getFirstObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  console.info('fileAsset displayName: ', fileAsset.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.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callbacke	AsyncCallback<T>	Yes	Callback invoked to return the next file asset.

Example

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

async function example() {
  console.info('getNextObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  await fetchResult.getFirstObject();
  if (!fetchResult.isAfterLast()) {
    fetchResult.getNextObject((err, fileAsset) => {
      if (fileAsset != undefined) {
        console.info('fileAsset displayName: ', fileAsset.displayName);
      } else {
        console.error('fileAsset failed with err: ' + err);
      }
    });
  }
}

getNextObject

getNextObject(): Promise<T>

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

System capability: SystemCapability.FileManagement.UserFileManager.Core

Return value

Type	Description
Promise<T>	Promise used to return the next object in the result set.

Example

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

async function example() {
  console.info('getNextObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  await fetchResult.getFirstObject();
  if (!fetchResult.isAfterLast()) {
    let fileAsset: userFileManager.FileAsset = await fetchResult.getNextObject();
    console.info('fileAsset displayName: ', fileAsset.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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<T>	Yes	Callback invoked to return the last file asset obtained.

Example

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

async function example() {
  console.info('getLastObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  fetchResult.getLastObject((err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('fileAsset displayName: ', fileAsset.displayName);
    } else {
      console.error('fileAsset failed with err: ' + err);
    }
  });
}

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.UserFileManager.Core

Return value

Type	Description
Promise<T>	Promise used to return the last object in the result set.

Example

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

async function example() {
  console.info('getLastObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getLastObject();
  console.info('fileAsset displayName: ', fileAsset.displayName);
}

getPositionObject

getPositionObject(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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the file asset to obtain. The value starts from 0.
callback	AsyncCallback<T>	Yes	Callback invoked to return the file asset obtained.

Error codes

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

ID	Error Message
13900020	if type index is not number.

Example

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

async function example() {
  console.info('getPositionObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  fetchResult.getPositionObject(0, (err, fileAsset) => {
    if (fileAsset != undefined) {
      console.info('fileAsset displayName: ', fileAsset.displayName);
    } else {
      console.error('fileAsset failed with err: ' + err);
    }
  });
}

getPositionObject

getPositionObject(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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the file asset to obtain. The value starts from 0.

Return value

Type	Description
Promise<T>	Promise used to return the file asset obtained.

Error codes

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

ID	Error Message
13900020	if type index is not number.

Example

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

async function example() {
  console.info('getPositionObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getPositionObject(0);
  console.info('fileAsset displayName: ', fileAsset.displayName);
}

getAllObject¹⁰⁺

getAllObject(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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<T>>	Yes	Callback invoked to return an array of all file assets in the result set.

Example

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

async function example() {
  console.info('getAllObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  fetchResult.getAllObject((err, fileAssetList) => {
    if (fileAssetList != undefined) {
      console.info('fileAssetList length: ', fileAssetList.length);
    } else {
      console.error('fileAssetList failed with err:' + err);
    }
  });
}

getAllObject¹⁰⁺

getAllObject(): 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.UserFileManager.Core

Return value

Type	Description
Promise<Array<T>>	Promise used to return an array of all file assets in the result set.

Example

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

async function example() {
  console.info('getAllObjectDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
  let fileAssetList: Array<userFileManager.FileAsset> = await fetchResult.getAllObject();
  console.info('fileAssetList length: ', fileAssetList.length);
}

Album

Provides APIs to manage albums.

Attributes

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
albumType¹⁰⁺	AlbumType	Yes	No	Type of the album.
albumSubType¹⁰⁺	AlbumSubType	Yes	No	Subtype of the album.
albumName	string	Yes	Yes for a user album; no for a system album.	Name of the album.
albumUri	string	Yes	No	URI of the album.
count	number	Yes	No	Number of files in the album.
coverUri	string	Yes	Yes for a user album; no for a system album.	URI of the cover file of the album.

getPhotoAssets

getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): 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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the image and video assets.
callback	AsyncCallback<FetchResult<FileAsset>>	Yes	Callback invoked to return the image and video assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

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

  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let albumList: userFileManager.FetchResult<userFileManager.Album> = await mgr.getPhotoAlbums(albumFetchOptions);
  let album: userFileManager.Album = await albumList.getFirstObject();
  album.getPhotoAssets(fetchOption, (err, albumFetchResult) => {
    if (albumFetchResult != undefined) {
      console.info('album getPhotoAssets successfully, getCount: ' + albumFetchResult.getCount());
    } else {
      console.error('album getPhotoAssets failed with error: ' + err);
    }
  });
}

getPhotoAssets

getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;

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

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the image and video assets.

Return value

Type	Description
Promise<FetchResult<FileAsset>>	Promise used to return the image and video assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

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

  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  const albumList: userFileManager.FetchResult<userFileManager.Album> = await mgr.getPhotoAlbums(albumFetchOptions);
  const album: userFileManager.Album = await albumList.getFirstObject();
  album.getPhotoAssets(fetchOption).then((albumFetchResult) => {
    console.info('album getFileAssets successfully, getCount: ' + albumFetchResult.getCount());
  }).catch((err: BusinessError) => {
    console.error('album getFileAssets failed with error: ' + err);
  });
}

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.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  console.info('albumCommitModifyDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let albumFetchOptions: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };
  const albumList: userFileManager.FetchResult<userFileManager.Album> = await mgr.getPhotoAlbums(albumFetchOptions);
  const album: userFileManager.Album = await albumList.getFirstObject();
  album.albumName = 'hello';
  album.commitModify((err) => {
    if (err != undefined) {
      console.error('commitModify failed with error: ' + err);
    } 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.UserFileManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

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: userFileManager.AlbumFetchOptions = {
    predicates: predicates
  };
  try {
    let albumList: userFileManager.FetchResult<userFileManager.Album> = await mgr.getPhotoAlbums(albumFetchOptions);
    let album: userFileManager.Album = await albumList.getFirstObject();
    album.albumName = 'hello';
    album.commitModify().then(() => {
      console.info('commitModify successfully');
    }).catch((err: BusinessError) => {
      console.error('commitModify failed with error: ' + err);
    });
  } catch (err) {
    console.error('getPhotoAlbums failed. message = ', err);
  }
}

addPhotoAssets¹⁰⁺

addPhotoAssets(assets: Array<FileAsset>, 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.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image and video assets to add.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('addPhotoAssetsDemoCallback');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.addPhotoAssets([asset], (err) => {
      if (err === undefined) {
        console.info('album addPhotoAssets successfully');
      } else {
        console.error('album addPhotoAssets failed with error: ' + err);
      }
    });
  } catch (err) {
    console.error('addPhotoAssetsDemoCallback failed with error: ' + err);
  }
}

addPhotoAssets¹⁰⁺

addPhotoAssets(assets: Array<FileAsset>): 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.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image and video assets to add.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('addPhotoAssetsDemoPromise');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await mgr.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.addPhotoAssets([asset]).then(() => {
      console.info('album addPhotoAssets successfully');
    }).catch((err: BusinessError) => {
      console.error('album addPhotoAssets failed with error: ' + err);
    });
  } catch (err) {
    console.error('addPhotoAssetsDemoPromise failed with error: ' + err);
  }
}

removePhotoAssets¹⁰⁺

removePhotoAssets(assets: Array<FileAsset>, 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.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image and video assets to remove.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('removePhotoAssetsDemoCallback');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.removePhotoAssets([asset], (err) => {
      if (err === undefined) {
        console.info('album removePhotoAssets successfully');
      } else {
        console.error('album removePhotoAssets failed with error: ' + err);
      }
    });
  } catch (err) {
    console.error('removePhotoAssetsDemoCallback failed with error: ' + err);
  }
}

removePhotoAssets¹⁰⁺

removePhotoAssets(assets: Array<FileAsset>): 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.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image and video assets to remove.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('removePhotoAssetsDemoPromise');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.removePhotoAssets([asset]).then(() => {
      console.info('album removePhotoAssets successfully');
    }).catch((err: BusinessError) => {
      console.error('album removePhotoAssets failed with error: ' + err);
    });
  } catch (err) {
    console.error('removePhotoAssetsDemoPromise failed with error: ' + err);
  }
}

recoverPhotoAssets¹⁰⁺

recoverPhotoAssets(assets: Array<FileAsset>, callback: AsyncCallback<void>): void;

Recovers image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image or video assets to recover.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('recoverPhotoAssetsDemoCallback');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.recoverPhotoAssets([asset], (err) => {
      if (err === undefined) {
        console.info('album recoverPhotoAssets successfully');
      } else {
        console.error('album recoverPhotoAssets failed with error: ' + err);
      }
    });
  } catch (err) {
    console.error('recoverPhotoAssetsDemoCallback failed with error: ' + err);
  }
}

recoverPhotoAssets¹⁰⁺

recoverPhotoAssets(assets: Array<FileAsset>): Promise<void>;

Recovers image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses a promise to return the result.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image or video assets to recover.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('recoverPhotoAssetsDemoPromise');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.recoverPhotoAssets([asset]).then(() => {
      console.info('album recoverPhotoAssets successfully');
    }).catch((err: BusinessError) => {
      console.error('album recoverPhotoAssets failed with error: ' + err);
    });
  } catch (err) {
    console.error('recoverPhotoAssetsDemoPromise failed with error: ' + err);
  }
}

deletePhotoAssets¹⁰⁺

deletePhotoAssets(assets: Array<FileAsset>, callback: AsyncCallback<void>): void;

Deletes image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses an asynchronous callback to return the result.

CAUTION: This operation is irreversible. The file assets deleted cannot be restored. Exercise caution when performing this operation.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image or video assets to delete.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('deletePhotoAssetsDemoCallback');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.deletePhotoAssets([asset], (err) => {
      if (err === undefined) {
        console.info('album deletePhotoAssets successfully');
      } else {
        console.error('album deletePhotoAssets failed with error: ' + err);
      }
    });
  } catch (err) {
    console.error('deletePhotoAssetsDemoCallback failed with error: ' + err);
  }
}

deletePhotoAssets¹⁰⁺

deletePhotoAssets(assets: Array<FileAsset>): Promise<void>;

Deletes image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses a promise to return the result.

CAUTION: This operation is irreversible. The file assets deleted cannot be restored. Exercise caution when performing this operation.

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<FileAsset>	Yes	Array of the image or video assets to delete.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
13900020	if PhotoAssets is invalid.

Example

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

async function example() {
  try {
    console.info('deletePhotoAssetsDemoPromise');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: userFileManager.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let albumFetchResult: userFileManager.FetchResult<userFileManager.Album> = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
    let album: userFileManager.Album = await albumFetchResult.getFirstObject();
    let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await album.getPhotoAssets(fetchOption);
    let asset: userFileManager.FileAsset = await fetchResult.getFirstObject();
    album.deletePhotoAssets([asset]).then(() => {
      console.info('album deletePhotoAssets successfully');
    }).catch((err: BusinessError) => {
      console.error('album deletePhotoAssets failed with error: ' + err);
    });
  } catch (err) {
    console.error('deletePhotoAssetsDemoPromise failed with error: ' + err);
  }
}

PrivateAlbum

Provides APIs for managing the system albums.

This API will be discarded. Use Album instead.

Attributes

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
albumName	string	Yes	Yes	Name of the album.
albumUri	string	Yes	No	URI of the album.
dateModified	number	Yes	No	Date when the album was last modified.
count	number	Yes	No	Number of files in the album.
coverUri	string	Yes	No	URI of the cover file of the album.

getPhotoAssets

getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;

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

This API will be deprecated. Use Album.getPhotoAssets instead.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the image and video assets.
callback	AsyncCallback<FetchResult<FileAsset>>	Yes	Callback invoked to return the image and video assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

async function example() {
  console.info('privateAlbumGetFileAssetsDemoCallback');
  let albumList: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  const trashAlbum: userFileManager.PrivateAlbum = await albumList.getFirstObject();
  trashAlbum.getPhotoAssets(fetchOption, (err, fetchResult) => {
    if (fetchResult != undefined) {
      let count = fetchResult.getCount();
      console.info('fetchResult.count = ', count);
    } else {
      console.error('getFileAssets failed, message = ', err);
    }
  });
}

getPhotoAssets

getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;

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

This API will be deprecated. Use Album.getPhotoAssets instead.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
options	FetchOptions	Yes	Options for fetching the image and video assets.

Return value

Type	Description
Promise:FetchResult<FileAsset>	Promise used to return the image and video assets obtained.

Error codes

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

ID	Error Message
13900020	if type options is not FetchOptions.

Example

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

async function example() {
  console.info('privateAlbumGetFileAssetsDemoPromise');
  let albumList: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  const trashAlbum: userFileManager.PrivateAlbum = await albumList.getFirstObject();
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await trashAlbum.getPhotoAssets(fetchOption);
  let count = fetchResult.getCount();
  console.info('fetchResult.count = ', count);
}

delete

delete(uri: string, callback: AsyncCallback<void>): void;

Deletes a file from the system album. Only the files in the trash can be deleted.

This API will be deprecated. Use Album.deletePhotoAssets instead.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the file to delete.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  console.info('privateAlbumDeleteCallback');
  let albumList: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let trashAlbum: userFileManager.PrivateAlbum = await albumList.getFirstObject();
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await trashAlbum.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  let deleteFileUri = fileAsset.uri;
  trashAlbum.delete(deleteFileUri, (err) => {
    if (err != undefined) {
      console.error('trashAlbum.delete failed, message = ', err);
    } else {
      console.info('trashAlbum.delete successfully');
    }
  });
}

delete

delete(uri: string): Promise<void>;

Deletes a file from the system album. Only the files in the trash can be deleted.

This API will be deprecated. Use Album.deletePhotoAssets instead.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the file to delete.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  console.info('privateAlbumDeleteDemoPromise');
  let albumList: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let trashAlbum: userFileManager.PrivateAlbum = await albumList.getFirstObject();
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await trashAlbum.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  let deleteFileUri = fileAsset.uri;
  trashAlbum.delete(deleteFileUri).then(() => {
    console.info('trashAlbum.delete successfully');
  }).catch((err: BusinessError) => {
    console.error('trashAlbum.delete failed, message = ', err);
  });
}

recover

recover(uri: string, callback: AsyncCallback<void>): void;

Recovers a file in the system album. Only the files in the trash can be recovered.

This API will be deprecated. Use Album.recoverPhotoAssets instead.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the file to recover.
callback	AsyncCallback<void>	Yes	Callback that returns no value.

Example

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

async function example() {
  console.info('privateAlbumRecoverDemoCallback');
  let albumList: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let trashAlbum: userFileManager.PrivateAlbum = await albumList.getFirstObject();
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await trashAlbum.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  let recoverFileUri: string = fileAsset.uri;
  trashAlbum.recover(recoverFileUri, (err) => {
    if (err != undefined) {
      console.error('trashAlbum.recover failed, message = ', err);
    } else {
      console.info('trashAlbum.recover successfully');
    }
  });
}

recover

recover(uri: string): Promise<void>;

Recovers a file in the system album. Only the files in the trash can be recovered.

This API will be deprecated. Use Album.recoverPhotoAssets instead.

Required permissions: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO

System capability: SystemCapability.FileManagement.UserFileManager.Core

Parameters

Name	Type	Mandatory	Description
uri	string	Yes	URI of the file to recover.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

async function example() {
  console.info('privateAlbumRecoverDemoPromise');
  let albumList: userFileManager.FetchResult<userFileManager.PrivateAlbum> = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOption: userFileManager.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  let trashAlbum: userFileManager.PrivateAlbum = await albumList.getFirstObject();
  let fetchResult: userFileManager.FetchResult<userFileManager.FileAsset> = await trashAlbum.getPhotoAssets(fetchOption);
  let fileAsset: userFileManager.FileAsset = await fetchResult.getFirstObject();
  let recoverFileUri: string = fileAsset.uri;
  trashAlbum.recover(recoverFileUri).then(() => {
    console.info('trashAlbum.recover successfully');
  }).catch((err: BusinessError) => {
    console.error('trashAlbum.recover failed, message = ', err);
  });
}

MemberType

Enumerates the member types.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
number	number	Yes	Yes	The member is a number.
string	string	Yes	Yes	The member is a string.
boolean	boolean	Yes	Yes	The member is a Boolean value.

ChangeEvent

Enumerates the type of changes to observe.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
deviceChange	string	Yes	Yes	Device change.
albumChange	string	Yes	Yes	Album change.
imageChange	string	Yes	Yes	Image change.
audioChange	string	Yes	Yes	Audio change.
videoChange	string	Yes	Yes	Video change.
remoteFileChange	string	Yes	Yes	Remote file change.

PeerInfo

Defines information about a registered device.

System capability: SystemCapability.FileManagement.UserFileManager.DistributedCore

Name	Type	Readable	Writable	Description
deviceName	string	Yes	No	Name of the registered device.
networkId	string	Yes	No	Network ID of the registered device.
isOnline	boolean	Yes	No	Whether the registered device is online.

FileType

Enumerates media file types.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
IMAGE	1	Image.
VIDEO	2	Video.
AUDIO	3	Audio.

PhotoSubType¹⁰⁺

Enumerates the FileAsset types.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
DEFAULT	0	Default (photo) type.
SCREENSHOT	1	Screenshots and screen recording files.
CAMERA	2	Photos and videos taken by a camera.

PositionType¹⁰⁺

Enumerates the file location.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
LOCAL	1	Stored only on a local device.
CLOUD	2	Stored only on the cloud.
BOTH	3	Stored both on a local device and the cloud.

AlbumType¹⁰⁺

Enumerates the album types.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
USER	0	User album.
SYSTEM	1024	System album.

AlbumSubType¹⁰⁺

Enumerate the album subtypes.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
USER_GENERIC	1	User album.
FAVORITE	1025	Favorites.
VIDEO	1026	Video album.
HIDDEN	1027	Hidden album.
TRASH	1028	Recycle bin.
SCREENSHOT	1029	Album for screenshots and screen recording files.
CAMERA	1030	Album for photos and videos taken by the camera.
ANY	2147483647	Any album.

PrivateAlbumType

Enumerates the system album types.

This API will be deprecated. Use AlbumType and AlbumSubType instead.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
TYPE_FAVORITE	0	Favorites.
TYPE_TRASH	1	Recycle bin.

AudioKey

Defines the key information about an audio file.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
URI	uri	URI of the file.
DISPLAY_NAME	display_name	File name displayed.
DATE_ADDED	date_added	Date when the file was added. The value is the number of seconds elapsed since the Epoch time (00:00:00 UTC on January 1, 1970).
DATE_MODIFIED	date_modified	Date when the file content (not the file name) was last modified. The value is the number of seconds elapsed since the Epoch time.
TITLE	title	Title in the file.
ARTIST	artist	Author of the file.
AUDIOALBUM	audio_album	Audio album.
DURATION	duration	Duration, in ms.
FAVORITE	favorite	Whether the file is added to favorites.

ImageVideoKey

Defines the key information about an image or video file.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
URI	uri	URI of the file.
FILE_TYPE	file_type	Type of the file.
DISPLAY_NAME	display_name	File name displayed.
DATE_ADDED	date_added	Date when the file was added. The value is the number of seconds elapsed since the Epoch time.
DATE_MODIFIED	date_modified	Date when the file content (not the file name) was last modified. The value is the number of seconds elapsed since the Epoch time.
TITLE	title	Title of the file.
DURATION	duration	Duration, in ms.
WIDTH	width	Image width, in pixels.
HEIGHT	height	Image height, in pixels.
DATE_TAKEN	date_taken	Date when the file (photo) was taken. The value is the number of seconds elapsed since the Epoch time.
ORIENTATION	orientation	Orientation of the image file.
FAVORITE	favorite	Whether the file is added to favorites.
POSITION¹⁰⁺	position	File location type.
DATE_TRASHED¹⁰⁺	date_trashed	Date when the file was deleted. The value is the number of seconds elapsed since the Epoch time.
HIDDEN¹⁰⁺	hidden	Whether the file is hidden.
CAMERA_SHOT_KEY¹⁰⁺	camera_shot_key	Key for the Ultra Snapshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.)
USER_COMMENT¹⁰⁺	user_comment	User comment information.

AlbumKey

Defines the key album information.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
URI	uri	URI of the album.
FILE_TYPE	file_type	Type of the file.
ALBUM_NAME	album_name	Name of the album.
DATE_ADDED	date_added	Date when the album was added. The value is the number of seconds elapsed since the Epoch time.
DATE_MODIFIED	date_modified	Date when the album file content (not the album name) was last modified. The value is the number of seconds elapsed since the Epoch time.

PhotoCreateOptions¹⁰⁺

Options for creating an image or video asset.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Mandatory	Description
subType	PhotoSubType	No	Subtype of the image or video.
cameraShotKey	string	No	Key for the Ultra Snapshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.)

FetchOptions

Defines the options for fetching media files.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
fetchColumns	Array<string>	Yes	Yes	Options for fetching files based on the attributes in columns. If this parameter is left empty, files are fetched by URI, name, and type (the specific field names vary with the file asset or album object) by default. In addition, an error will be reported if get is called to obtain other attributes of this object. Example: fetchColumns: ['uri', 'title']
predicates	dataSharePredicates.DataSharePredicates	Yes	Yes	Predicates that specify the fetch criteria.

AlbumFetchOptions

Defines the options for fetching an album.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
predicates	dataSharePredicates.DataSharePredicates	Yes	Yes	Predicates that specify the fetch criteria.

ChangeData¹⁰⁺

Defines the return value of the listener callback.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Type	Readable	Writable	Description
type	NotifyType	Yes	No	Notification type.
uris	Array<string>	Yes	No	Array of all file asset or album URIs with the same NotifyType.
subUris	Array<string>	Yes	No	URIs of the changed files in the album.

NotifyType¹⁰⁺

Enumerates the notification event types.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
NOTIFY_ADD	0	A file asset or album is added.
NOTIFY_UPDATE	1	A file asset or album is updated.
NOTIFY_REMOVE	2	A file asset or album is removed.
NOTIFY_ALBUM_ADD_ASSET	3	A file asset is added to the album.
NOTIFY_ALBUM_REMOVE_ASSET	4	A file asset is removed from the album.

DefaultChangeUri¹⁰⁺

Enumerates the DefaultChangeUri subtypes.

System capability: SystemCapability.FileManagement.UserFileManager.Core

Name	Value	Description
DEFAULT_PHOTO_URI	file://media/Photo	Default PhotoAsset URI. The PhotoAsset change notifications are received based on this parameter and forSubUri{true}.
DEFAULT_ALBUM_URI	file://media/PhotoAlbum	Default album URI. Album change notifications are received based on this parameter and forSubUri{true}.
DEFAULT_AUDIO_URI	file://media/Audio	Default AudioAsset URI. The AudioAsset change notifications are received based on this parameter and forSubUri{true}.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)

标签云

@ohos.filemanagement.userFileManager (User Data Management)

Modules to Import

userFileManager.getUserFileMgr

UserFileManager

getPhotoAssets

getPhotoAssets

createPhotoAsset

createPhotoAsset

createPhotoAsset

createPhotoAsset

createPhotoAsset

createAudioAsset10+

createAudioAsset10+

createAlbum10+

createAlbum10+

deleteAlbums10+

deleteAlbums10+

getAlbums10+

getAlbums10+

getAlbums10+

getPhotoAlbums

getPhotoAlbums

getPrivateAlbum

getPrivateAlbum

getAudioAssets

getAudioAssets

delete

delete

getActivePeers

getActivePeers

getAllPeers

getAllPeers

getPhotoIndex10+

getPhotoIndex10+

release

release

on10+

off10+

on

off

FileAsset

Attributes

get

set

commitModify

commitModify

open

open

close

close

getThumbnail

getThumbnail

getThumbnail

favorite

favorite

setHidden10+

setHidden10+

getExif10+

getExif10+

setUserComment10+

setUserComment10+

FetchResult

getCount

isAfterLast

close

getFirstObject

getFirstObject

getNextObject

getNextObject

getLastObject

getLastObject

getPositionObject

getPositionObject

getAllObject10+

getAllObject10+

Album

Attributes

getPhotoAssets

getPhotoAssets

createAudioAsset¹⁰⁺

createAudioAsset¹⁰⁺

createAlbum¹⁰⁺

createAlbum¹⁰⁺

deleteAlbums¹⁰⁺

deleteAlbums¹⁰⁺

getAlbums¹⁰⁺

getAlbums¹⁰⁺

getAlbums¹⁰⁺

getPhotoIndex¹⁰⁺

getPhotoIndex¹⁰⁺

on¹⁰⁺

off¹⁰⁺

setHidden¹⁰⁺

setHidden¹⁰⁺

getExif¹⁰⁺

getExif¹⁰⁺

setUserComment¹⁰⁺

setUserComment¹⁰⁺

getAllObject¹⁰⁺

getAllObject¹⁰⁺

addPhotoAssets¹⁰⁺

addPhotoAssets¹⁰⁺

removePhotoAssets¹⁰⁺

removePhotoAssets¹⁰⁺

recoverPhotoAssets¹⁰⁺

recoverPhotoAssets¹⁰⁺

deletePhotoAssets¹⁰⁺

deletePhotoAssets¹⁰⁺

PhotoSubType¹⁰⁺

PositionType¹⁰⁺

AlbumType¹⁰⁺

AlbumSubType¹⁰⁺

PhotoCreateOptions¹⁰⁺

ChangeData¹⁰⁺

NotifyType¹⁰⁺

DefaultChangeUri¹⁰⁺