1# Class (MediaAlbumChangeRequest) 2 3> **NOTE** 4> 5> - 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. 6> - The initial APIs of this class are supported since API version 11. 7 8MediaAlbumChangeRequest implements [MediaChangeRequest](arkts-apis-photoAccessHelper-i.md#mediachangerequest11) 9 10MediaAlbumChangeRequest provides APIs for managing the media album change request. 11 12**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 13 14## Modules to Import 15 16```ts 17import { photoAccessHelper } from '@kit.MediaLibraryKit'; 18``` 19 20## constructor<sup>11+</sup> 21 22constructor(album: Album) 23 24Constructor used to initialize a new object. 25 26**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 27 28**Parameters** 29 30| Name | Type | Mandatory| Description | 31| -------- | ------------------------- | ---- | ---------- | 32| album | [Album](arkts-apis-photoAccessHelper-Album.md) | Yes | Album to change.| 33 34**Error codes** 35 36For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 37 38| ID| Error Message| 39| -------- | ---------------------------------------- | 40| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 41| 14000011 | System inner fail. | 42 43**Example** 44 45For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 46 47```ts 48import { dataSharePredicates } from '@kit.ArkData'; 49 50async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 51 console.info('MediaAlbumChangeRequest constructorDemo'); 52 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 53 let fetchOptions: photoAccessHelper.FetchOptions = { 54 fetchColumns: [], 55 predicates: predicates 56 }; 57 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions); 58 let album: photoAccessHelper.Album = await fetchResult.getFirstObject(); 59 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 60} 61``` 62 63## getAlbum<sup>11+</sup> 64 65getAlbum(): Album 66 67Obtains the album in the current album change request. 68 69**NOTE**: For the change request for creating an album, this API returns **null** before [applyChanges](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11) is called to apply the changes. 70 71**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 72 73**Return value** 74 75| Type | Description | 76| --------------------------------------- | ----------------- | 77| [Album](arkts-apis-photoAccessHelper-Album.md) | Album obtained.| 78 79**Error codes** 80 81For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 82 83| ID| Error Message| 84| -------- | ---------------------------------------- | 85| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 86| 14000011 | System inner fail. | 87 88**Example** 89 90For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 91 92```ts 93async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 94 console.info('getAlbumDemo'); 95 try { 96 // Ensure that the user album exists in the gallery. 97 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 98 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 99 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 100 let changeRequestAlbum: photoAccessHelper.Album = albumChangeRequest.getAlbum(); 101 console.info('change request album uri: ' + changeRequestAlbum.albumUri); 102 } catch (err) { 103 console.error(`getAlbumDemo failed with error: ${err.code}, ${err.message}`); 104 } 105} 106``` 107 108## setAlbumName<sup>11+</sup> 109 110setAlbumName(name: string): void 111 112Sets the album name. 113 114The album name must comply with the following specifications: 115- It does not exceed 255 characters. 116- It does not contain any of the following characters:<br> . \ / : * ? " ' ` < > | { } [ ] 117- It is case-insensitive. 118- Duplicate album names are not allowed. 119 120**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 121 122**Parameters** 123 124| Name | Type | Mandatory | Description | 125| ---------- | ------- | ---- | ---------------------------------- | 126| name | string | Yes | Album name to set.| 127 128**Error codes** 129 130For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 131 132| ID| Error Message| 133| -------- | ---------------------------------------- | 134| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 135| 14000011 | System inner fail. | 136 137**Example** 138 139For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 140 141```ts 142async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 143 console.info('setAlbumNameDemo'); 144 try { 145 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 146 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 147 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 148 let newAlbumName: string = 'newAlbumName' + new Date().getTime(); 149 albumChangeRequest.setAlbumName(newAlbumName); 150 await phAccessHelper.applyChanges(albumChangeRequest); 151 console.info('setAlbumName successfully'); 152 } catch (err) { 153 console.error(`setAlbumNameDemo failed with error: ${err.code}, ${err.message}`); 154 } 155} 156``` 157 158## addAssets<sup>11+</sup> 159 160addAssets(assets: Array<PhotoAsset>): void 161 162Add assets to the album. 163 164**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 165 166**Parameters** 167 168| Name | Type | Mandatory | Description | 169| ---------- | ------- | ---- | ---------------------------------- | 170| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | Yes | Array of assets to add.| 171 172**Error codes** 173 174For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 175 176| ID| Error Message| 177| -------- | ---------------------------------------- | 178| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 179| 14000011 | System inner fail. | 180| 14000016 | Operation Not Support. | 181 182**Example** 183 184For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 185 186```ts 187import { dataSharePredicates } from '@kit.ArkData'; 188 189async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 190 console.info('addAssetsDemo'); 191 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 192 let fetchOptions: photoAccessHelper.FetchOptions = { 193 fetchColumns: [], 194 predicates: predicates 195 }; 196 try { 197 // Ensure that user albums and photos exist in Gallery. 198 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 199 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 200 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 201 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 202 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 203 albumChangeRequest.addAssets([asset]); 204 await phAccessHelper.applyChanges(albumChangeRequest); 205 console.info('addAssets successfully'); 206 } catch (err) { 207 console.error(`addAssetsDemo failed with error: ${err.code}, ${err.message}`); 208 } 209} 210``` 211 212## removeAssets<sup>11+</sup> 213 214removeAssets(assets: Array<PhotoAsset>): void 215 216Removes assets from the album. 217 218**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 219 220**Parameters** 221 222| Name | Type | Mandatory | Description | 223| ---------- | ------- | ---- | ---------------------------------- | 224| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | Yes | Array of assets to remove.| 225 226**Error codes** 227 228For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 229 230| ID| Error Message| 231| -------- | ---------------------------------------- | 232| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 233| 14000011 | System inner fail. | 234| 14000016 | Operation Not Support. | 235 236**Example** 237 238For details about how to create a phAccessHelper instance, see the example provided in [photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper). 239 240```ts 241import { dataSharePredicates } from '@kit.ArkData'; 242 243async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 244 console.info('removeAssetsDemo'); 245 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 246 let fetchOptions: photoAccessHelper.FetchOptions = { 247 fetchColumns: [], 248 predicates: predicates 249 }; 250 try { 251 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 252 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 253 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions); 254 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 255 256 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 257 albumChangeRequest.removeAssets([asset]); 258 await phAccessHelper.applyChanges(albumChangeRequest); 259 console.info('removeAssets successfully'); 260 } catch (err) { 261 console.error(`removeAssetsDemo failed with error: ${err.code}, ${err.message}`); 262 } 263} 264``` 265