• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
25
26**开发步骤**
27
281. 设置获取收藏夹的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.FAVORITE。
292. 调用PhotoAccessHelper.getAlbums接口获取收藏夹对象。
30
31```ts
32import photoAccessHelper from '@ohos.file.photoAccessHelper';
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### 收藏图片和视频（仅向系统应用开放）
49
50通过[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)接口将图片或视频设置为收藏。
51
52**前提条件**
53
54- 获取相册管理模块photoAccessHelper实例。
55- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
56
57下面将以收藏一张图片为例。
58
59**开发步骤**
60
611. [获取指定媒体资源](photoAccessHelper-resource-guidelines.md#获取指定媒体资源)。
622. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为收藏。
633. 调用PhotoAccessHelper.applyChanges接口提交收藏图片的变更请求。
64
65```ts
66import dataSharePredicates from '@ohos.data.dataSharePredicates';
67import photoAccessHelper from '@ohos.file.photoAccessHelper';
68const context = getContext(this);
69let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
70
71async function example() {
72  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
73  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
74  let fetchOptions: photoAccessHelper.FetchOptions = {
75    fetchColumns: [],
76    predicates: predicates
77  };
78
79  try {
80    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
81    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
82    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
83    let favoriteState = true;
84    assetChangeRequest.setFavorite(favoriteState);
85    await phAccessHelper.applyChanges(assetChangeRequest);
86  } catch (err) {
87    console.error('setFavorite failed with err: ' + err);
88  }
89}
90```
91
92### 获取收藏夹中的图片和视频
93
94先[获取收藏夹对象](#获取收藏夹对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取收藏夹中的资源。
95
96**前提条件**
97
98- 获取相册管理模块photoAccessHelper实例。
99- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
100
101下面以获取收藏夹中的一张图片为例。
102
103**开发步骤**
104
1051. [获取收藏夹对象](#获取收藏夹对象)。
1062. 建立图片检索条件，用于获取图片。
1073. 调用Album.getAssets接口获取图片资源。
1084. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
109
110```ts
111import dataSharePredicates from '@ohos.data.dataSharePredicates';
112import photoAccessHelper from '@ohos.file.photoAccessHelper';
113const context = getContext(this);
114let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
115
116async function example() {
117  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
118  let fetchOptions: photoAccessHelper.FetchOptions = {
119    fetchColumns: [],
120    predicates: predicates
121  };
122
123  try {
124    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
125    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
126    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
127
128    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
129    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
130    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
131    photoFetchResult.close();
132    albumFetchResult.close();
133  } catch (err) {
134    console.error('favorite failed with err: ' + err);
135  }
136}
137```
138
139### 取消收藏图片或视频（仅向系统应用开放）
140
141通过[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)接口将图片或视频取消收藏。
142
143**前提条件**
144
145- 获取相册管理模块photoAccessHelper实例。
146- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
147
148下面以将一张图片取消收藏为例。
149
150**开发步骤**
151
1521. [获取收藏夹中的图片和视频](#获取收藏夹中的图片和视频)。
1532. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为取消收藏。
1543. 调用PhotoAccessHelper.applyChanges接口提交取消收藏图片的变更请求。
155
156
157```ts
158import dataSharePredicates from '@ohos.data.dataSharePredicates';
159import photoAccessHelper from '@ohos.file.photoAccessHelper';
160const context = getContext(this);
161let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
162
163async function example() {
164  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
165  let fetchOptions: photoAccessHelper.FetchOptions = {
166    fetchColumns: [],
167    predicates: predicates
168  };
169
170  try {
171    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
172    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
173    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
174
175    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
176    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
177    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
178
179    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
180    let favoriteState = false;
181    assetChangeRequest.setFavorite(favoriteState);
182    await phAccessHelper.applyChanges(assetChangeRequest);
183    photoFetchResult.close();
184    albumFetchResult.close();
185  } catch (err) {
186    console.error('setFavorite failed with err: ' + err);
187  }
188}
189```
190
191## 视频相册
192
193视频相册属于系统相册，用户文件中属于视频类型的媒体文件会自动加入到视频相册中。
194
195### 获取视频相册对象
196
197通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取视频相册对象。
198
199**前提条件**
200
201- 获取相册管理模块photoAccessHelper实例。
202- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
203
204**开发步骤**
205
2061. 设置获取视频相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.VIDEO。
2072. 调用PhotoAccessHelper.getAlbums接口获取视频相册。
208
209```ts
210import photoAccessHelper from '@ohos.file.photoAccessHelper';
211const context = getContext(this);
212let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
213
214async function example() {
215  try {
216    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
217    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
218    console.info('get video album successfully, albumUri: ' + album.albumUri);
219    fetchResult.close();
220  } catch (err) {
221    console.error('get video album failed with err: ' + err);
222  }
223}
224```
225
226### 获取视频相册中的视频
227
228先[获取视频相册对象](#获取视频相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取视频相册对象中的视频资源。
229
230**前提条件**
231
232- 获取相册管理模块photoAccessHelper实例。
233- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
234
235下面以获取视频相册中的一个视频为例。
236
237**开发步骤**
238
2391. 先[获取视频相册对象](#获取视频相册对象)。
2402. 建立视频检索条件，用于获取视频。
2413. 调用Album.getAssets接口获取视频资源。
2424. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个视频。
243
244```ts
245import dataSharePredicates from '@ohos.data.dataSharePredicates';
246import photoAccessHelper from '@ohos.file.photoAccessHelper';
247const context = getContext(this);
248let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
249
250async function example() {
251  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
252  let fetchOptions: photoAccessHelper.FetchOptions = {
253    fetchColumns: [],
254    predicates: predicates
255  };
256
257  try {
258    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
259    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
260    console.info('get video album successfully, albumUri: ' + album.albumUri);
261
262    let videoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
263    let photoAsset: photoAccessHelper.PhotoAsset = await videoFetchResult.getFirstObject();
264    console.info('video album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
265    videoFetchResult.close();
266    albumFetchResult.close();
267  } catch (err) {
268    console.error('video failed with err: ' + err);
269  }
270}
271```
272
273## 截屏和录屏相册（仅向系统应用开放）
274
275截屏和录屏相册属于系统相册，用户文件中属于截屏和录屏的媒体文件会自动加入到截屏和录屏相册中。
276
277### 获取截屏和录屏相册对象
278
279通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取截屏和录屏相册对象。
280
281**前提条件**
282
283- 获取相册管理模块photoAccessHelper实例。
284- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
285
286**开发步骤**
287
2881. 设置获取截屏和录屏相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.SCREENSHOT。
2892. 调用PhotoAccessHelper.getAlbums接口获取截屏和录屏相册。
290
291```ts
292import photoAccessHelper from '@ohos.file.photoAccessHelper';
293const context = getContext(this);
294let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
295
296async function example() {
297  try {
298    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
299    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
300    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
301    fetchResult.close();
302  } catch (err) {
303    console.error('get screenshot album failed with err: ' + err);
304  }
305}
306```
307
308### 获取截屏和录屏相册中的媒体资源
309
310先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取截屏和录屏相册对象中的媒体资源。
311
312**前提条件**
313
314- 获取相册管理模块photoAccessHelper实例。
315- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
316
317下面以获取截屏和录屏相册中的一个媒体资源为例。
318
319**开发步骤**
320
3211. 先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。
3222. 建立检索条件，用于获取媒体资源。
3233. 调用Album.getAssets接口获取媒体资源。
3244. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个媒体资源。
325
326```ts
327import dataSharePredicates from '@ohos.data.dataSharePredicates';
328import photoAccessHelper from '@ohos.file.photoAccessHelper';
329const context = getContext(this);
330let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
331
332async function example() {
333  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
334  let fetchOptions: photoAccessHelper.FetchOptions = {
335    fetchColumns: [],
336    predicates: predicates
337  };
338
339  try {
340    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
341    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
342    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
343
344    let screenshotFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
345    let photoAsset: photoAccessHelper.PhotoAsset = await screenshotFetchResult.getFirstObject();
346    console.info('screenshot album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
347    screenshotFetchResult.close();
348    albumFetchResult.close();
349  } catch (err) {
350    console.error('screenshot album failed with err: ' + err);
351  }
352}
353```
354