Class (MediaAlbumChangeRequest)

MediaAlbumChangeRequest implements MediaChangeRequest.

MediaAlbumChangeRequest provides APIs for managing the media album change request.

NOTE

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

Modules to Import

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

Attributes

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

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Name	Type	Read-Only	Optional	Description
comment23+	string	Yes	No	Used to verify the MediaChangeRequest type. If a class (such as MediaAlbumChangeRequest) object can be accessed, it is an implementation class of MediaChangeRequest.

constructor¹¹⁺

constructor(album: Album)

Constructor used to initialize a new object.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
album	Album	Yes	Album to change.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

Example

For details about how to create a phAccessHelper instance, see the example provided in photoAccessHelper.getPhotoAccessHelper.

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

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

getAlbum¹¹⁺

getAlbum(): Album

Obtains the album in the current album change request.

NOTE

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

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Type	Description
Album	Album obtained.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14000011	System inner fail.

Example

For details about how to create a phAccessHelper instance, see the example provided in photoAccessHelper.getPhotoAccessHelper.

async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
  console.info('getAlbumDemo');
  try {
    // Ensure that the user album exists in the gallery.
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
    let changeRequestAlbum: photoAccessHelper.Album = albumChangeRequest.getAlbum();
    console.info('change request album uri: ' + changeRequestAlbum.albumUri);
  } catch (err) {
    console.error(`getAlbumDemo failed with error: ${err.code}, ${err.message}`);
  }
}

setAlbumName¹¹⁺

setAlbumName(name: string): void

Sets the album name.

The album name must meet the following requirements:

• The total length of the album name must be between 1 and 255 characters.
• It must not contain any invalid characters, which are:
  . \ / : * ? " ' ` < > | { } [ ]
• It is case-insensitive.
• Duplicate album names are not allowed.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Album name to set.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	System inner fail.

Example

For details about how to create a phAccessHelper instance, see the example provided in photoAccessHelper.getPhotoAccessHelper.

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

addAssets¹¹⁺

addAssets(assets: Array<PhotoAsset>): void

Add assets to the album.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<PhotoAsset>	Yes	Array of assets to add.

Error codes

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

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

Example

For details about how to create a phAccessHelper instance, see the example provided in photoAccessHelper.getPhotoAccessHelper.

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

async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
  console.info('addAssetsDemo');
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    // Ensure that user albums and photos exist in Gallery.
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC);
    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
    albumChangeRequest.addAssets([asset]);
    await phAccessHelper.applyChanges(albumChangeRequest);
    console.info('addAssets successfully');
  } catch (err) {
    console.error(`addAssetsDemo failed with error: ${err.code}, ${err.message}`);
  }
}

removeAssets¹¹⁺

removeAssets(assets: Array<PhotoAsset>): void

Removes assets from the album.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
assets	Array<PhotoAsset>	Yes	Array of assets to remove.

Error codes

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

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

Example

For details about how to create a phAccessHelper instance, see the example provided in photoAccessHelper.getPhotoAccessHelper.

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

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

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