1# Managing User Albums
2
3The **photoAccessHelper** module provides APIs for user album management, including creating or deleting a user album, adding images and videos to a user album, and deleting images and videos from a user album.
4
5> **NOTE**
6>
7> - Before you get started, obtain a **PhotoAccessHelper** instance and apply for required permissions. For details, see [Before You Start](photoAccessHelper-preparation.md).
8> - Unless otherwise specified, the **PhotoAccessHelper** instance obtained in the **Before You Start** section is used to call **photoAccessHelper** APIs. If the code for obtaining the **PhotoAccessHelper** instance is missing, an error will be reported to indicate that **photoAccessHelper** is not defined.
9
10To ensure application running efficiency, most **PhotoAccessHelper** APIs are asynchronously implemented in callback or promise mode. The following examples use promise-based APIs. For details about the APIs, see [Album Management](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md).
11Unless otherwise specified, all the media assets to be obtained in this document exist in the database. If no media asset is obtained when the sample code is executed, check whether the media assets exist in the database.
12
13<!--Del-->
14## Creating a User Album (for System Applications Only)
15
16Use [MediaAlbumChangeRequest.createAlbumRequest](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#createalbumrequest11) and [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to create a user album.
17
18The album name must meet the following requirements:
19
20- The album name cannot exceed 255 characters.
21- The album name cannot contain any of the following characters:<br>. \ / : * ? " ' ` < > | { } [ ]
22- The album name is case-insensitive.
23- Duplicate album names are not allowed.
24
25**Prerequisites**
26
27- A **PhotoAccessHelper** instance is obtained.
28- The application has the ohos.permission.WRITE_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
29
30Example: Create a user album.
31
32**How to Develop**
33
341. Set the name of the album.
352. Call **MediaAlbumChangeRequest.createAlbumRequest** to create an album change request object.
363. Call **PhotoAccessHelper.applyChanges** to apply the changes.
37
38```ts
39import photoAccessHelper from '@ohos.file.photoAccessHelper';
40const context = getContext(this);
41let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
42
43async function example() {
44  try {
45    let albumName = 'albumName';
46    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
47    await phAccessHelper.applyChanges(albumChangeRequest);
48    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
49    console.info('create album successfully, album name: ' + album.albumName + ' uri: ' + album.albumUri);
50  } catch (err) {
51    console.error('create album failed with err: ' + err);
52  }
53}
54```
55<!--DelEnd-->
56
57## Obtaining a User Album
58
59Use [PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2) to obtain user albums.
60
61**Prerequisites**
62
63- A **PhotoAccessHelper** instance is obtained.
64- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
65
66Example: Obtain the user album **albumName**.
67
68**How to Develop**
69
701. Set **fetchOptions** for obtaining the user album.
712. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
723. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
73
74```ts
75import dataSharePredicates from '@ohos.data.dataSharePredicates';
76import photoAccessHelper from '@ohos.file.photoAccessHelper';
77const context = getContext(this);
78let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
79
80async function example() {
81  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
82  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
83  predicates.equalTo(albumName, 'albumName');
84  let fetchOptions: photoAccessHelper.FetchOptions = {
85    fetchColumns: [],
86    predicates: predicates
87  };
88
89  try {
90    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
91    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
92    console.info('getAlbums successfully, albumName: ' + album.albumName);
93    fetchResult.close();
94  } catch (err) {
95    console.error('getAlbums failed with err: ' + err);
96  }
97}
98```
99
100## Renaming a User Album
101
102To rename a user album, modify the **Album.albumName** attribute of the album.
103
104Use the [FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult) APIs to obtain the user album to rename, use [MediaAlbumChangeRequest.setAlbumName](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#setalbumname11) to rename the user album, and use [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to apply the changes to the database.
105
106The new user album names must comply with the following requirements:
107
108- The album name cannot exceed 255 characters.
109- The album name cannot contain any of the following characters:<br>. \ / : * ? " ' ` < > | { } [ ]
110- The album name is case-insensitive.
111- Duplicate album names are not allowed.
112
113**Prerequisites**
114
115- A **PhotoAccessHelper** instance is obtained.
116- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
117
118Example: Rename the user album **albumName**.
119
120**How to Develop**
121
1221. Set **fetchOptions** for obtaining the user album.
1232. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
1243. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
1254. Call **MediaAlbumChangeRequest.setAlbumName** to set a new album name.
1265. Call **PhotoAccessHelper.applyChanges** to save the new album name to the database.
127
128```ts
129import dataSharePredicates from '@ohos.data.dataSharePredicates';
130import photoAccessHelper from '@ohos.file.photoAccessHelper';
131const context = getContext(this);
132let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
133
134async function example() {
135  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
136  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
137  predicates.equalTo(albumName, 'albumName');
138  let fetchOptions: photoAccessHelper.FetchOptions = {
139    fetchColumns: [],
140    predicates: predicates
141  };
142
143  try {
144    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
145    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
146    console.info('getAlbums successfully, albumName: ' + album.albumName);
147    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
148    let newAlbumName: string = 'newAlbumName';
149    albumChangeRequest.setAlbumName(newAlbumName);
150    await phAccessHelper.applyChanges(albumChangeRequest);
151    console.info('setAlbumName successfully, new albumName: ' + album.albumName);
152    fetchResult.close();
153  } catch (err) {
154    console.error('setAlbumName failed with err: ' + err);
155  }
156}
157```
158
159## Adding Images or Videos to a User Album
160
161[Obtain the user album](#obtaining-a-user-album) and the images or videos to be added to the album, and then call [MediaAlbumChangeRequest.addAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addassets11) and [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to add the images or videos to the user album.
162
163**Prerequisites**
164
165- A **PhotoAccessHelper** instance is obtained.
166- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
167
168Example: Add an image to the user album **albumName**.
169
170**How to Develop**
171
1721. Set **albumFetchOptions** for obtaining the user album.
1732. Set **photoFetchOptions** for obtaining the image.
1743. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
1754. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject) to obtain the first user album.
1765. Call [PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets) to obtain image assets.
1776. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject) to obtain the first image from the result set.
1787. Call **MediaAlbumChangeRequest.addAssets** to add the image to the user album.
1798. Call **PhotoAccessHelper.applyChanges** to apply the changes.
180
181```ts
182import dataSharePredicates from '@ohos.data.dataSharePredicates';
183import photoAccessHelper from '@ohos.file.photoAccessHelper';
184const context = getContext(this);
185let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
186
187async function example() {
188  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
189  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
190  albumPredicates.equalTo(albumName, 'albumName');
191  let albumFetchOptions: photoAccessHelper.FetchOptions = {
192    fetchColumns: [],
193    predicates: albumPredicates
194  };
195
196  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
197  let photoFetchOptions: photoAccessHelper.FetchOptions = {
198    fetchColumns: [],
199    predicates: photoPredicates
200  };
201
202  try {
203    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
204    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
205    console.info('getAlbums successfully, albumName: ' + album.albumName);
206    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(photoFetchOptions);
207    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
208    console.info('getAssets successfully, albumName: ' + photoAsset.displayName);
209    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
210    albumChangeRequest.addAssets([photoAsset]);
211    await phAccessHelper.applyChanges(albumChangeRequest);
212    console.info('succeed to add ' + photoAsset.displayName + ' to ' + album.albumName);
213    albumFetchResult.close();
214    photoFetchResult.close();
215  } catch (err) {
216    console.error('addAssets failed with err: ' + err);
217  }
218}
219```
220
221## Obtaining Images and Videos in a User Album
222
223[Obtain the user album](#obtaining-a-user-album), and call [Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3) to obtain the assets in the user album.
224
225**Prerequisites**
226
227- A **PhotoAccessHelper** instance is obtained.
228- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
229
230Example: Obtain an image in the user album **albumName**.
231
232**How to Develop**
233
2341. Set **albumFetchOptions** for obtaining the user album.
2352. Set **photoFetchOptions** for obtaining the image.
2363. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
2374. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
2385. Call **Album.getAssets** to obtain the media assets in the user album.
2396. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the result set.
240
241```ts
242import dataSharePredicates from '@ohos.data.dataSharePredicates';
243import photoAccessHelper from '@ohos.file.photoAccessHelper';
244const context = getContext(this);
245let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
246
247async function example() {
248  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
249  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
250  albumPredicates.equalTo(albumName, 'albumName');
251  let albumFetchOptions: photoAccessHelper.FetchOptions = {
252    fetchColumns: [],
253    predicates: albumPredicates
254  };
255
256  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
257  let photoFetchOptions: photoAccessHelper.FetchOptions = {
258    fetchColumns: [],
259    predicates: photoPredicates
260  };
261
262  try {
263    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
264    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
265    console.info('getAlbums successfully, albumName: ' + album.albumName);
266    let photoFetchResult = await album.getAssets(photoFetchOptions);
267    let photoAsset = await photoFetchResult.getFirstObject();
268    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
269    albumFetchResult.close();
270    photoFetchResult.close();
271  } catch (err) {
272    console.error('album getAssets failed with err: ' + err);
273  }
274}
275```
276
277## Removing Images and Videos from a User Album
278
279[Obtain the user album](#obtaining-a-user-album), and call [Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3) to obtain the assets in the user album.
280
281Select the assets to remove, and use [MediaAlbumChangeRequest.removeAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#removeassets11) and [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to remove the selected media assets.
282
283**Prerequisites**
284
285- A **PhotoAccessHelper** instance is obtained.
286- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
287
288Example: Remove an image from the user album **albumName**.
289
290**How to Develop**
291
2921. Set **albumFetchOptions** for obtaining the user album.
2932. Set **photoFetchOptions** for obtaining the image.
2943. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
2954. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
2965. Call **Album.getAssets** to obtain the media assets.
2976. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the result set.
2987. Call **MediaAlbumChangeRequest.removeAssets** to remove the image from the user album.
2998. Call **PhotoAccessHelper.applyChanges** to apply the changes.
300
301```ts
302import dataSharePredicates from '@ohos.data.dataSharePredicates';
303import photoAccessHelper from '@ohos.file.photoAccessHelper';
304const context = getContext(this);
305let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
306
307async function example() {
308  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
309  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
310  albumPredicates.equalTo(albumName, 'albumName');
311  let albumFetchOptions: photoAccessHelper.FetchOptions = {
312    fetchColumns: [],
313    predicates: albumPredicates
314  };
315
316  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
317  let photoFetchOptions: photoAccessHelper.FetchOptions = {
318    fetchColumns: [],
319    predicates: photoPredicates
320  };
321
322  try {
323    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
324    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
325    console.info('getAlbums successfully, albumName: ' + album.albumName);
326    let photoFetchResult = await album.getAssets(photoFetchOptions);
327    let photoAsset = await photoFetchResult.getFirstObject();
328    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
329    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
330    albumChangeRequest.removeAssets([photoAsset]);
331    await phAccessHelper.applyChanges(albumChangeRequest);
332    console.info('succeed to remove ' + photoAsset.displayName + ' from ' + album.albumName);
333    albumFetchResult.close();
334    photoFetchResult.close();
335  } catch (err) {
336    console.error('removeAssets failed with err: ' + err);
337  }
338}
339```
340
341<!--Del-->
342## Deleting a User Album (for System Applications Only)
343
344[Obtain the user album](#obtaining-a-user-album), and call [MediaAlbumChangeRequest.deleteAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#deletealbums11) to delete the user album.
345
346**Prerequisites**
347
348- A **PhotoAccessHelper** instance is obtained.
349- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
350
351Example: Delete the user album **albumName**.
352
353**How to Develop**
354
3551. Set **fetchOptions** for obtaining the user album.
3562. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
3573. Call **FetchResult.getFirstObject** to obtain the first user album.
3584. Call **MediaAlbumChangeRequest.deleteAlbums** to delete the user album.
359
360```ts
361import dataSharePredicates from '@ohos.data.dataSharePredicates';
362import photoAccessHelper from '@ohos.file.photoAccessHelper';
363const context = getContext(this);
364let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
365
366async function example() {
367  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
368  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
369  predicates.equalTo(albumName, 'albumName');
370  let fetchOptions: photoAccessHelper.FetchOptions = {
371    fetchColumns: [],
372    predicates: predicates
373  };
374
375  try {
376    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
377    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
378    console.info('getAlbums successfully, albumName: ' + album.albumName);
379    await photoAccessHelper.MediaAlbumChangeRequest.deleteAlbums(context, [album]);
380    fetchResult.close();
381  } catch (err) {
382    console.error('deleteAlbums failed with err: ' + err);
383  }
384}
385```
386<!--DelEnd-->
387