1# Managing System Albums
2
3The **photoAccessHelper** module provides APIs for managing system albums, including **Favorites**, **Videos**, and **Screenshots**.
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## Favorites
15
16**Favorites** is a system album. Favoriting an image or video adds the image or video to **Favorites**; unfavoriting an image or video removes the image or video from **Favorites**.
17
18### Obtaining a Favorites Object
19
20Use [PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2) to obtain a **Favorites** object.
21
22**Prerequisites**
23
24- A **PhotoAccessHelper** instance is obtained.
25- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
26
27**How to Develop**
28
291. Set the album type to **photoAccessHelper.AlbumType.SYSTEM** and the album subtype to **photoAccessHelper.AlbumSubtype.FAVORITE**.
302. Call **PhotoAccessHelper.getAlbums** to obtain a **Favorites** object.
31
32```ts
33import { photoAccessHelper } from '@kit.MediaLibraryKit';
34const context = getContext(this);
35let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
36
37async function example() {
38  try {
39    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
40    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
41    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
42    fetchResult.close();
43  } catch (err) {
44    console.error('get favorite album failed with err: ' + err);
45  }
46}
47```
48
49<!--Del-->
50### Favoriting an Image or Video (for System Applications Only)
51
52Use [MediaAssetChangeRequest.setFavorite](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#setfavorite11) and [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to add an image or video to **Favorites**.
53
54**Prerequisites**
55
56- A **PhotoAccessHelper** instance is obtained.
57- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
58
59Example: Favorite an image.
60
61**How to Develop**
62
631. [Obtain media assets](photoAccessHelper-resource-guidelines.md#obtaining-media-assets).
642. Call **MediaAssetChangeRequest.setFavorite** to set **favoriteState** to **true**.
653. Call **PhotoAccessHelper.applyChanges** to apply the changes.
66
67```ts
68import { dataSharePredicates } from '@kit.ArkData';
69import { photoAccessHelper } from '@kit.MediaLibraryKit';
70const context = getContext(this);
71let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
72
73async function example() {
74  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
75  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
76  let fetchOptions: photoAccessHelper.FetchOptions = {
77    fetchColumns: [],
78    predicates: predicates
79  };
80
81  try {
82    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
83    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
84    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
85    let favoriteState = true;
86    assetChangeRequest.setFavorite(favoriteState);
87    await phAccessHelper.applyChanges(assetChangeRequest);
88  } catch (err) {
89    console.error('setFavorite failed with err: ' + err);
90  }
91}
92```
93<!--DelEnd-->
94
95### Obtaining Images and Videos in Favorites
96
97[Obtain a **Favorites** object](#obtaining-a-favorites-object), and call [Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3) to obtain the assets in **Favorites**.
98
99**Prerequisites**
100
101- A **PhotoAccessHelper** instance is obtained.
102- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
103
104Example: Obtain an image from **Favorites**.
105
106**How to Develop**
107
1081. [Obtain a **Favorites** object](#obtaining-a-favorites-object).
1092. Set **fetchOptions** for obtaining the image.
1103. Call **Album.getAssets** to obtain the image assets.
1114. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the result set.
112
113```ts
114import { dataSharePredicates } from '@kit.ArkData';
115import { photoAccessHelper } from '@kit.MediaLibraryKit';
116const context = getContext(this);
117let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
118
119async function example() {
120  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
121  let fetchOptions: photoAccessHelper.FetchOptions = {
122    fetchColumns: [],
123    predicates: predicates
124  };
125
126  try {
127    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
128    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
129    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
130
131    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
132    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
133    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
134    photoFetchResult.close();
135    albumFetchResult.close();
136  } catch (err) {
137    console.error('favorite failed with err: ' + err);
138  }
139}
140```
141
142<!--Del-->
143### Unfavoriting an Image or Video (for System Applications Only)
144
145Use [MediaAssetChangeRequest.setFavorite](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#setfavorite11) and [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to remove an image or video from **Favorites**.
146
147**Prerequisites**
148
149- A **PhotoAccessHelper** instance is obtained.
150- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
151
152Example: Unfavorite an image.
153
154**How to Develop**
155
1561. [Obtain the image in **Favorites**](#obtaining-images-and-videos-in-favorites).
1572. Call **MediaAssetChangeRequest.setFavorite** to set **favoriteState** to **false**.
1583. Call **PhotoAccessHelper.applyChanges** to apply the changes.
159
160
161```ts
162import { dataSharePredicates } from '@kit.ArkData';
163import { photoAccessHelper } from '@kit.MediaLibraryKit';
164const context = getContext(this);
165let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
166
167async function example() {
168  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
169  let fetchOptions: photoAccessHelper.FetchOptions = {
170    fetchColumns: [],
171    predicates: predicates
172  };
173
174  try {
175    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
176    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
177    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
178
179    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
180    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
181    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
182
183    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
184    let favoriteState = false;
185    assetChangeRequest.setFavorite(favoriteState);
186    await phAccessHelper.applyChanges(assetChangeRequest);
187    photoFetchResult.close();
188    albumFetchResult.close();
189  } catch (err) {
190    console.error('setFavorite failed with err: ' + err);
191  }
192}
193```
194<!--DelEnd-->
195
196## Videos
197
198**Videos** is a system album that holds media assets of the video type in user files.
199
200### Obtaining a Videos Object
201
202Use [PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2) to obtain a **Videos** object.
203
204**Prerequisites**
205
206- A **PhotoAccessHelper** instance is obtained.
207- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
208
209**How to Develop**
210
2111. Set the album type to **photoAccessHelper.AlbumType.SYSTEM** and the album subtype to **photoAccessHelper.AlbumSubtype.VIDEO**.
2122. Use **PhotoAccessHelper.getAlbums** to obtain a **Videos** object.
213
214```ts
215import { photoAccessHelper } from '@kit.MediaLibraryKit';
216const context = getContext(this);
217let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
218
219async function example() {
220  try {
221    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
222    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
223    console.info('get video album successfully, albumUri: ' + album.albumUri);
224    fetchResult.close();
225  } catch (err) {
226    console.error('get video album failed with err: ' + err);
227  }
228}
229```
230
231### Obtaining a Video from Videos
232
233[Obtain a **Videos** object](#obtaining-a-videos-object), and call [Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3) to obtain the video assets in the **Videos** album.
234
235**Prerequisites**
236
237- A **PhotoAccessHelper** instance is obtained.
238- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
239
240Example: Obtain a video in **Videos**.
241
242**How to Develop**
243
2441. [Obtain a **Videos** object](#obtaining-a-videos-object).
2452. Set **fetchOptions** for obtaining the video.
2463. Call **Album.getAssets** to obtain video assets.
2474. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first video asset.
248
249```ts
250import { dataSharePredicates } from '@kit.ArkData';
251import { photoAccessHelper } from '@kit.MediaLibraryKit';
252const context = getContext(this);
253let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
254
255async function example() {
256  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
257  let fetchOptions: photoAccessHelper.FetchOptions = {
258    fetchColumns: [],
259    predicates: predicates
260  };
261
262  try {
263    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
264    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
265    console.info('get video album successfully, albumUri: ' + album.albumUri);
266
267    let videoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
268    let photoAsset: photoAccessHelper.PhotoAsset = await videoFetchResult.getFirstObject();
269    console.info('video album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
270    videoFetchResult.close();
271    albumFetchResult.close();
272  } catch (err) {
273    console.error('video failed with err: ' + err);
274  }
275}
276```
277
278<!--Del-->
279## Screenshots (for System Applications Only)
280
281**Screenshots** is a system album that holds user's screenshots and screen recording files.
282
283### Obtaining a Screenshots Object
284
285Use [PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2) to obtain a **Screenshots** object.
286
287**Prerequisites**
288
289- A **PhotoAccessHelper** instance is obtained.
290- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
291
292**How to Develop**
293
2941. Set the album type to **photoAccessHelper.AlbumType.SYSTEM** and the album subtype to **photoAccessHelper.AlbumSubtype.SCREENSHOT**.
2952. Use **PhotoAccessHelper.getAlbums** to obtain a **Screenshots** object.
296
297```ts
298import { photoAccessHelper } from '@kit.MediaLibraryKit';
299const context = getContext(this);
300let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
301
302async function example() {
303  try {
304    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
305    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
306    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
307    fetchResult.close();
308  } catch (err) {
309    console.error('get screenshot album failed with err: ' + err);
310  }
311}
312```
313
314### Obtaining Media Assets in Screenshots
315
316[Obtain a **Screenshots** object](#obtaining-a-screenshots-object), and call [Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3) to obtain the media assets in **Screenshots**.
317
318**Prerequisites**
319
320- A **PhotoAccessHelper** instance is obtained.
321- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
322
323Example: Obtain a media asset from **Screenshots**.
324
325**How to Develop**
326
3271. [Obtain a **Screenshots** object](#obtaining-a-screenshots-object).
3282. Set **fetchOptions** for obtaining the media asset.
3293. Call **Album.getAssets** to obtain media assets.
3304. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first media asset.
331
332```ts
333import { dataSharePredicates } from '@kit.ArkData';
334import { photoAccessHelper } from '@kit.MediaLibraryKit';
335const context = getContext(this);
336let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
337
338async function example() {
339  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
340  let fetchOptions: photoAccessHelper.FetchOptions = {
341    fetchColumns: [],
342    predicates: predicates
343  };
344
345  try {
346    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
347    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
348    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
349
350    let screenshotFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
351    let photoAsset: photoAccessHelper.PhotoAsset = await screenshotFetchResult.getFirstObject();
352    console.info('screenshot album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
353    screenshotFetchResult.close();
354    albumFetchResult.close();
355  } catch (err) {
356    console.error('screenshot album failed with err: ' + err);
357  }
358}
359```
360<!--DelEnd-->
361