1# 系统相册资源使用指导
2
3photoAccessHelper仅提供开发者对收藏夹、视频相册、截屏和录屏相册进行相关操作。
4
5> **说明：**
6>
7> 在进行功能开发前，请开发者查阅[开发准备](photoAccessHelper-preparation.md)，了解如何获取相册管理模块实例和如何申请相册管理模块功能开发相关权限。
8> 文档中使用到PhotoAccessHelper的地方默认为使用开发准备中获取的对象，如未添加此段代码报PhotoAccessHelper未定义的错误请自行添加。
9
10为了保证应用的运行效率，大部分photoAccessHelper的接口调用都是异步的。以下异步调用的API示例均采用Promise函数，更多方式可以查阅[API参考](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md)。
11如无特别说明，文档中涉及的待获取的资源均视为已经预置且在数据库中存在相应数据。如出现按照示例代码执行出现获取资源为空的情况请确认文件是否已预置，数据库中是否存在该文件的数据。
12
13## 收藏夹
14
15收藏夹属于系统相册，对图片或视频设置收藏时会自动将其加入到收藏夹中，取消收藏则会从收藏夹中移除。
16
17### 获取收藏夹对象
18
19通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取收藏夹对象。
20
21**前提条件**
22
23- 获取相册管理模块photoAccessHelper实例。
24- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
25
26**开发步骤**
27
281. 设置获取收藏夹的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.FAVORITE。
292. 调用PhotoAccessHelper.getAlbums接口获取收藏夹对象。
30
31```ts
32import { photoAccessHelper } from '@kit.MediaLibraryKit';
33const context = getContext(this);
34let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
35
36async function example() {
37  try {
38    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
39    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
40    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
41    fetchResult.close();
42  } catch (err) {
43    console.error('get favorite album failed with err: ' + err);
44  }
45}
46```
47
48<!--Del-->
49### 收藏图片和视频（仅向系统应用开放）
50
51通过[MediaAssetChangeRequest.setFavorite](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#setfavorite11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口将图片或视频设置为收藏。
52
53**前提条件**
54
55- 获取相册管理模块photoAccessHelper实例。
56- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
57
58下面将以收藏一张图片为例。
59
60**开发步骤**
61
621. [获取指定媒体资源](photoAccessHelper-resource-guidelines.md#获取指定媒体资源)。
632. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为收藏。
643. 调用PhotoAccessHelper.applyChanges接口提交收藏图片的变更请求。
65
66```ts
67import { dataSharePredicates } from '@kit.ArkData';
68import { photoAccessHelper } from '@kit.MediaLibraryKit';
69const context = getContext(this);
70let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
71
72async function example() {
73  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
74  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
75  let fetchOptions: photoAccessHelper.FetchOptions = {
76    fetchColumns: [],
77    predicates: predicates
78  };
79
80  try {
81    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
82    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
83    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
84    let favoriteState = true;
85    assetChangeRequest.setFavorite(favoriteState);
86    await phAccessHelper.applyChanges(assetChangeRequest);
87  } catch (err) {
88    console.error('setFavorite failed with err: ' + err);
89  }
90}
91```
92<!--DelEnd-->
93
94### 获取收藏夹中的图片和视频
95
96先[获取收藏夹对象](#获取收藏夹对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取收藏夹中的资源。
97
98**前提条件**
99
100- 获取相册管理模块photoAccessHelper实例。
101- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
102
103下面以获取收藏夹中的一张图片为例。
104
105**开发步骤**
106
1071. [获取收藏夹对象](#获取收藏夹对象)。
1082. 建立图片检索条件，用于获取图片。
1093. 调用Album.getAssets接口获取图片资源。
1104. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
111
112```ts
113import { dataSharePredicates } from '@kit.ArkData';
114import { photoAccessHelper } from '@kit.MediaLibraryKit';
115const context = getContext(this);
116let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
117
118async function example() {
119  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
120  let fetchOptions: photoAccessHelper.FetchOptions = {
121    fetchColumns: [],
122    predicates: predicates
123  };
124
125  try {
126    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
127    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
128    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
129
130    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
131    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
132    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
133    photoFetchResult.close();
134    albumFetchResult.close();
135  } catch (err) {
136    console.error('favorite failed with err: ' + err);
137  }
138}
139```
140
141<!--Del-->
142### 取消收藏图片或视频（仅向系统应用开放）
143
144通过[MediaAssetChangeRequest.setFavorite](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#setfavorite11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口将图片或视频取消收藏。
145
146**前提条件**
147
148- 获取相册管理模块photoAccessHelper实例。
149- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
150
151下面以将一张图片取消收藏为例。
152
153**开发步骤**
154
1551. [获取收藏夹中的图片和视频](#获取收藏夹中的图片和视频)。
1562. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为取消收藏。
1573. 调用PhotoAccessHelper.applyChanges接口提交取消收藏图片的变更请求。
158
159
160```ts
161import { dataSharePredicates } from '@kit.ArkData';
162import { photoAccessHelper } from '@kit.MediaLibraryKit';
163const context = getContext(this);
164let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
165
166async function example() {
167  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
168  let fetchOptions: photoAccessHelper.FetchOptions = {
169    fetchColumns: [],
170    predicates: predicates
171  };
172
173  try {
174    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
175    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
176    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
177
178    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
179    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
180    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
181
182    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
183    let favoriteState = false;
184    assetChangeRequest.setFavorite(favoriteState);
185    await phAccessHelper.applyChanges(assetChangeRequest);
186    photoFetchResult.close();
187    albumFetchResult.close();
188  } catch (err) {
189    console.error('setFavorite failed with err: ' + err);
190  }
191}
192```
193<!--DelEnd-->
194
195## 视频相册
196
197视频相册属于系统相册，用户文件中属于视频类型的媒体文件会自动加入到视频相册中。
198
199### 获取视频相册对象
200
201通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取视频相册对象。
202
203**前提条件**
204
205- 获取相册管理模块photoAccessHelper实例。
206- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
207
208**开发步骤**
209
2101. 设置获取视频相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.VIDEO。
2112. 调用PhotoAccessHelper.getAlbums接口获取视频相册。
212
213```ts
214import { photoAccessHelper } from '@kit.MediaLibraryKit';
215const context = getContext(this);
216let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
217
218async function example() {
219  try {
220    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
221    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
222    console.info('get video album successfully, albumUri: ' + album.albumUri);
223    fetchResult.close();
224  } catch (err) {
225    console.error('get video album failed with err: ' + err);
226  }
227}
228```
229
230### 获取视频相册中的视频
231
232先[获取视频相册对象](#获取视频相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取视频相册对象中的视频资源。
233
234**前提条件**
235
236- 获取相册管理模块photoAccessHelper实例。
237- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
238
239下面以获取视频相册中的一个视频为例。
240
241**开发步骤**
242
2431. 先[获取视频相册对象](#获取视频相册对象)。
2442. 建立视频检索条件，用于获取视频。
2453. 调用Album.getAssets接口获取视频资源。
2464. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个视频。
247
248```ts
249import { dataSharePredicates } from '@kit.ArkData';
250import { photoAccessHelper } from '@kit.MediaLibraryKit';
251const context = getContext(this);
252let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
253
254async function example() {
255  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
256  let fetchOptions: photoAccessHelper.FetchOptions = {
257    fetchColumns: [],
258    predicates: predicates
259  };
260
261  try {
262    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
263    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
264    console.info('get video album successfully, albumUri: ' + album.albumUri);
265
266    let videoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
267    let photoAsset: photoAccessHelper.PhotoAsset = await videoFetchResult.getFirstObject();
268    console.info('video album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
269    videoFetchResult.close();
270    albumFetchResult.close();
271  } catch (err) {
272    console.error('video failed with err: ' + err);
273  }
274}
275```
276
277<!--Del-->
278## 截屏和录屏相册（仅向系统应用开放）
279
280截屏和录屏相册属于系统相册，用户文件中属于截屏和录屏的媒体文件会自动加入到截屏和录屏相册中。
281
282### 获取截屏和录屏相册对象
283
284通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取截屏和录屏相册对象。
285
286**前提条件**
287
288- 获取相册管理模块photoAccessHelper实例。
289- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
290
291**开发步骤**
292
2931. 设置获取截屏和录屏相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.SCREENSHOT。
2942. 调用PhotoAccessHelper.getAlbums接口获取截屏和录屏相册。
295
296```ts
297import { photoAccessHelper } from '@kit.MediaLibraryKit';
298const context = getContext(this);
299let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
300
301async function example() {
302  try {
303    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
304    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
305    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
306    fetchResult.close();
307  } catch (err) {
308    console.error('get screenshot album failed with err: ' + err);
309  }
310}
311```
312
313### 获取截屏和录屏相册中的媒体资源
314
315先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取截屏和录屏相册对象中的媒体资源。
316
317**前提条件**
318
319- 获取相册管理模块photoAccessHelper实例。
320- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
321
322下面以获取截屏和录屏相册中的一个媒体资源为例。
323
324**开发步骤**
325
3261. 先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。
3272. 建立检索条件，用于获取媒体资源。
3283. 调用Album.getAssets接口获取媒体资源。
3294. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个媒体资源。
330
331```ts
332import { dataSharePredicates } from '@kit.ArkData';
333import { photoAccessHelper } from '@kit.MediaLibraryKit';
334const context = getContext(this);
335let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
336
337async function example() {
338  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
339  let fetchOptions: photoAccessHelper.FetchOptions = {
340    fetchColumns: [],
341    predicates: predicates
342  };
343
344  try {
345    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
346    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
347    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
348
349    let screenshotFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
350    let photoAsset: photoAccessHelper.PhotoAsset = await screenshotFetchResult.getFirstObject();
351    console.info('screenshot album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
352    screenshotFetchResult.close();
353    albumFetchResult.close();
354  } catch (err) {
355    console.error('screenshot album failed with err: ' + err);
356  }
357}
358```
359<!--DelEnd-->
360