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).
11
12Unless 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.
13
14<!--Del-->
15## Creating a User Album (for System Applications Only)
16
17Use [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.
18
19The album name must meet the following requirements:
20
21- The album name cannot exceed 255 characters.
22- The album name cannot contain any of the following characters:<br>. \ / : * ? " ' ` < > | { } [ ]
23- The album name is case-insensitive.
24- Duplicate album names are not allowed.
25
26**Prerequisites**
27
28- A **PhotoAccessHelper** instance is obtained.
29- The application has the ohos.permission.WRITE_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
30
31Example: Create a user album.
32
33**How to Develop**
34
351. Set the name of the album.
362. Call **MediaAlbumChangeRequest.createAlbumRequest** to create an album change request object.
373. Call **PhotoAccessHelper.applyChanges** to apply the changes.
38
39```ts
40import { photoAccessHelper } from '@kit.MediaLibraryKit';
41const context = getContext(this);
42let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
43
44async function example() {
45  try {
46    let albumName = 'albumName';
47    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
48    await phAccessHelper.applyChanges(albumChangeRequest);
49    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
50    console.info('create album successfully, album name: ' + album.albumName + ' uri: ' + album.albumUri);
51  } catch (err) {
52    console.error('create album failed with err: ' + err);
53  }
54}
55```
56<!--DelEnd-->
57
58## Obtaining a User Album
59
60Use [PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2) to obtain user albums.
61
62**Prerequisites**
63
64- A **PhotoAccessHelper** instance is obtained.
65- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
66
67Example: Obtain the user album **albumName**.
68
69**How to Develop**
70
711. Set **fetchOptions** for obtaining the user album.
722. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
733. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
74
75```ts
76import { dataSharePredicates } from '@kit.ArkData';
77import { photoAccessHelper } from '@kit.MediaLibraryKit';
78const context = getContext(this);
79let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
80
81async function example() {
82  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
83  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
84  predicates.equalTo(albumName, 'albumName');
85  let fetchOptions: photoAccessHelper.FetchOptions = {
86    fetchColumns: [],
87    predicates: predicates
88  };
89
90  try {
91    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
92    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
93    console.info('getAlbums successfully, albumName: ' + album.albumName);
94    fetchResult.close();
95  } catch (err) {
96    console.error('getAlbums failed with err: ' + err);
97  }
98}
99```
100
101## Renaming a User Album
102
103To rename a user album, modify the **Album.albumName** attribute of the album.
104
105Use [FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult) to obtain the user album to rename, use [MediaAlbumChangeRequest.setAlbumName](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#setalbumname11) to set the new name, and then use [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to apply the changes to the database.
106
107The new user album names must comply with the following requirements:
108
109- The album name cannot exceed 255 characters.
110- The album name cannot contain any of the following characters:<br>. \ / : * ? " ' ` < > | { } [ ]
111- The album name is case-insensitive.
112- Duplicate album names are not allowed.
113
114**Prerequisites**
115
116- A **PhotoAccessHelper** instance is obtained.
117- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
118
119Example: Rename the user album **albumName**.
120
121**How to Develop**
122
1231. Set **fetchOptions** for obtaining the user album.
1242. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
1253. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
1264. Call **MediaAlbumChangeRequest.setAlbumName** to set a new album name.
1275. Call **PhotoAccessHelper.applyChanges** to save the new album name to the database.
128
129```ts
130import { dataSharePredicates } from '@kit.ArkData';
131import { photoAccessHelper } from '@kit.MediaLibraryKit';
132const context = getContext(this);
133let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
134
135async function example() {
136  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
137  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
138  predicates.equalTo(albumName, 'albumName');
139  let fetchOptions: photoAccessHelper.FetchOptions = {
140    fetchColumns: [],
141    predicates: predicates
142  };
143
144  try {
145    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
146    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
147    console.info('getAlbums successfully, albumName: ' + album.albumName);
148    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
149    let newAlbumName: string = 'newAlbumName';
150    albumChangeRequest.setAlbumName(newAlbumName);
151    await phAccessHelper.applyChanges(albumChangeRequest);
152    console.info('setAlbumName successfully, new albumName: ' + album.albumName);
153    fetchResult.close();
154  } catch (err) {
155    console.error('setAlbumName failed with err: ' + err);
156  }
157}
158```
159
160## Adding Images or Videos to a User Album
161
162[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.
163
164**Prerequisites**
165
166- A **PhotoAccessHelper** instance is obtained.
167- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
168
169Example: Add an image to the user album **albumName**.
170
171**How to Develop**
172
1731. Set **albumFetchOptions** for obtaining the user album.
1742. Set **photoFetchOptions** for obtaining the image.
1753. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
1764. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject) to obtain the first user album.
1775. Call [PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets) to obtain image assets.
1786. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject) to obtain the first image from the result set.
1797. Call **MediaAlbumChangeRequest.addAssets** to add the image to the user album.
1808. Call **PhotoAccessHelper.applyChanges** to apply the changes.
181
182```ts
183import { dataSharePredicates } from '@kit.ArkData';
184import { photoAccessHelper } from '@kit.MediaLibraryKit';
185const context = getContext(this);
186let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
187
188async function example() {
189  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
190  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
191  albumPredicates.equalTo(albumName, 'albumName');
192  let albumFetchOptions: photoAccessHelper.FetchOptions = {
193    fetchColumns: [],
194    predicates: albumPredicates
195  };
196
197  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
198  let photoFetchOptions: photoAccessHelper.FetchOptions = {
199    fetchColumns: [],
200    predicates: photoPredicates
201  };
202
203  try {
204    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
205    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
206    console.info('getAlbums successfully, albumName: ' + album.albumName);
207    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(photoFetchOptions);
208    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
209    console.info('getAssets successfully, albumName: ' + photoAsset.displayName);
210    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
211    albumChangeRequest.addAssets([photoAsset]);
212    await phAccessHelper.applyChanges(albumChangeRequest);
213    console.info('succeed to add ' + photoAsset.displayName + ' to ' + album.albumName);
214    albumFetchResult.close();
215    photoFetchResult.close();
216  } catch (err) {
217    console.error('addAssets failed with err: ' + err);
218  }
219}
220```
221
222## Obtaining Images and Videos in a User Album
223
224[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.
225
226**Prerequisites**
227
228- A **PhotoAccessHelper** instance is obtained.
229- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
230
231Example: Obtain an image in the user album **albumName**.
232
233**How to Develop**
234
2351. Set **albumFetchOptions** for obtaining the user album.
2362. Set **photoFetchOptions** for obtaining the image.
2373. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
2384. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
2395. Call **Album.getAssets** to obtain the media assets in the user album.
2406. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the result set.
241
242```ts
243import { dataSharePredicates } from '@kit.ArkData';
244import { photoAccessHelper } from '@kit.MediaLibraryKit';
245const context = getContext(this);
246let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
247
248async function example() {
249  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
250  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
251  albumPredicates.equalTo(albumName, 'albumName');
252  let albumFetchOptions: photoAccessHelper.FetchOptions = {
253    fetchColumns: [],
254    predicates: albumPredicates
255  };
256
257  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
258  let photoFetchOptions: photoAccessHelper.FetchOptions = {
259    fetchColumns: [],
260    predicates: photoPredicates
261  };
262
263  try {
264    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
265    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
266    console.info('getAlbums successfully, albumName: ' + album.albumName);
267    let photoFetchResult = await album.getAssets(photoFetchOptions);
268    let photoAsset = await photoFetchResult.getFirstObject();
269    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
270    albumFetchResult.close();
271    photoFetchResult.close();
272  } catch (err) {
273    console.error('album getAssets failed with err: ' + err);
274  }
275}
276```
277
278## Removing Images and Videos from a User Album
279
280[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.
281
282Select 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.
283
284**Prerequisites**
285
286- A **PhotoAccessHelper** instance is obtained.
287- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
288
289Example: Remove an image from the user album **albumName**.
290
291**How to Develop**
292
2931. Set **albumFetchOptions** for obtaining the user album.
2942. Set **photoFetchOptions** for obtaining the image.
2953. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
2964. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first user album.
2975. Call **Album.getAssets** to obtain the media assets.
2986. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the result set.
2997. Call **MediaAlbumChangeRequest.removeAssets** to remove the image from the user album.
3008. Call **PhotoAccessHelper.applyChanges** to apply the changes.
301
302```ts
303import { dataSharePredicates } from '@kit.ArkData';
304import { photoAccessHelper } from '@kit.MediaLibraryKit';
305const context = getContext(this);
306let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
307
308async function example() {
309  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
310  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
311  albumPredicates.equalTo(albumName, 'albumName');
312  let albumFetchOptions: photoAccessHelper.FetchOptions = {
313    fetchColumns: [],
314    predicates: albumPredicates
315  };
316
317  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
318  let photoFetchOptions: photoAccessHelper.FetchOptions = {
319    fetchColumns: [],
320    predicates: photoPredicates
321  };
322
323  try {
324    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
325    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
326    console.info('getAlbums successfully, albumName: ' + album.albumName);
327    let photoFetchResult = await album.getAssets(photoFetchOptions);
328    let photoAsset = await photoFetchResult.getFirstObject();
329    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
330    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
331    albumChangeRequest.removeAssets([photoAsset]);
332    await phAccessHelper.applyChanges(albumChangeRequest);
333    console.info('succeed to remove ' + photoAsset.displayName + ' from ' + album.albumName);
334    albumFetchResult.close();
335    photoFetchResult.close();
336  } catch (err) {
337    console.error('removeAssets failed with err: ' + err);
338  }
339}
340```
341
342<!--Del-->
343## Deleting a User Album (for System Applications Only)
344
345[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.
346
347**Prerequisites**
348
349- A **PhotoAccessHelper** instance is obtained.
350- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
351
352Example: Delete the user album **albumName**.
353
354**How to Develop**
355
3561. Set **fetchOptions** for obtaining the user album.
3572. Call **PhotoAccessHelper.getAlbums** to obtain user albums.
3583. Call **FetchResult.getFirstObject** to obtain the first user album.
3594. Call **MediaAlbumChangeRequest.deleteAlbums** to delete the user album.
360
361```ts
362import { dataSharePredicates } from '@kit.ArkData';
363import { photoAccessHelper } from '@kit.MediaLibraryKit';
364const context = getContext(this);
365let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
366
367async function example() {
368  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
369  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
370  predicates.equalTo(albumName, 'albumName');
371  let fetchOptions: photoAccessHelper.FetchOptions = {
372    fetchColumns: [],
373    predicates: predicates
374  };
375
376  try {
377    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
378    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
379    console.info('getAlbums successfully, albumName: ' + album.albumName);
380    await photoAccessHelper.MediaAlbumChangeRequest.deleteAlbums(context, [album]);
381    fetchResult.close();
382  } catch (err) {
383    console.error('deleteAlbums failed with err: ' + err);
384  }
385}
386```
387<!--DelEnd-->
388