• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 系统相册资源使用指导
2<!--Kit: Media Library Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @yixiaoff-->
5<!--Designer: @liweilu1-->
6<!--Tester: @xchaosioda-->
7<!--Adviser: @zengyawen-->
8
9photoAccessHelper提供对收藏夹、视频相册、截屏和录屏相册的相关操作。
10
11> **说明：**
12>
13> 在进行功能开发前，请查阅[开发准备](photoAccessHelper-preparation.md)，了解如何获取相册管理模块实例及申请相关权限。
14> 文档中使用到PhotoAccessHelper的地方，默认使用[开发准备](photoAccessHelper-preparation.md)中获取的对象，如未添加此段代码提示PhotoAccessHelper未定义的错误请自行添加。
15
16为了保证应用的运行效率，大部分photoAccessHelper的接口调用都是异步的。以下异步调用的API示例均采用Promise函数，更多方式可以查阅[API参考](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper.md)。
17如无特别说明，文档中涉及的待获取的资源均视为已经预置且在数据库中存在相应数据。如出现按照示例代码执行出现获取资源为空的情况，请确认文件是否已预置，数据库中是否存在该文件的数据。
18
19## 收藏夹
20
21收藏夹属于系统相册，对图片或视频设置收藏时会自动将其加入到收藏夹中，取消收藏则会从收藏夹中移除。
22
23### 获取收藏夹对象
24
25通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getalbums-2)接口获取收藏夹对象。
26
27**前提条件**
28
29- 获取相册管理模块photoAccessHelper实例。
30- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
31
32**开发步骤**
33
341. 设置获取收藏夹的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.FAVORITE。
352. 调用PhotoAccessHelper.getAlbums接口获取收藏夹对象。
36
37```ts
38import { photoAccessHelper } from '@kit.MediaLibraryKit';
39
40async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
41  try {
42    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
43    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
44    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
45    fetchResult.close();
46  } catch (err) {
47    console.error('get favorite album failed with err: ' + err);
48  }
49}
50```
51
52<!--Del-->
53### 收藏图片和视频（仅向系统应用开放）
54
55通过[MediaAssetChangeRequest.setFavorite](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#setfavorite11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11)接口将图片或视频设置为收藏。
56
57**前提条件**
58
59- 获取相册管理模块photoAccessHelper实例。
60- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
61
62下面将以收藏一张图片为例。
63
64**开发步骤**
65
661. [获取指定媒体资源](photoAccessHelper-resource-guidelines.md#获取指定媒体资源)。
672. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为收藏。
683. 调用PhotoAccessHelper.applyChanges接口提交收藏图片的变更请求。
69
70```ts
71import { dataSharePredicates } from '@kit.ArkData';
72import { photoAccessHelper } from '@kit.MediaLibraryKit';
73
74async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
75  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
76  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
77  let fetchOptions: photoAccessHelper.FetchOptions = {
78    fetchColumns: [],
79    predicates: predicates
80  };
81
82  try {
83    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
84    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
85    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
86    let favoriteState = true;
87    assetChangeRequest.setFavorite(favoriteState);
88    await phAccessHelper.applyChanges(assetChangeRequest);
89  } catch (err) {
90    console.error('setFavorite failed with err: ' + err);
91  }
92}
93```
94<!--DelEnd-->
95
96### 获取收藏夹中的图片和视频
97
98先[获取收藏夹对象](#获取收藏夹对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-AbsAlbum.md#getassets-1)接口获取收藏夹中的资源。
99
100**前提条件**
101
102- 获取相册管理模块photoAccessHelper实例。
103- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
104
105下面以获取收藏夹中的一张图片为例。
106
107**开发步骤**
108
1091. [获取收藏夹对象](#获取收藏夹对象)。
1102. 建立图片检索条件，用于获取图片。
1113. 调用Album.getAssets接口获取图片资源。
1124. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一张图片。
113
114```ts
115import { dataSharePredicates } from '@kit.ArkData';
116import { photoAccessHelper } from '@kit.MediaLibraryKit';
117
118async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
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/arkts-apis-photoAccessHelper-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';
163
164async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
165  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
166  let fetchOptions: photoAccessHelper.FetchOptions = {
167    fetchColumns: [],
168    predicates: predicates
169  };
170
171  try {
172    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
173    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
174    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
175
176    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
177    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
178    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
179
180    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
181    let favoriteState = false;
182    assetChangeRequest.setFavorite(favoriteState);
183    await phAccessHelper.applyChanges(assetChangeRequest);
184    photoFetchResult.close();
185    albumFetchResult.close();
186  } catch (err) {
187    console.error('setFavorite failed with err: ' + err);
188  }
189}
190```
191<!--DelEnd-->
192
193## 视频相册
194
195视频相册属于系统相册，用户文件中属于视频类型的媒体文件会自动加入到视频相册中。
196
197### 获取视频相册对象
198
199通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getalbums-2)接口获取视频相册对象。
200
201**前提条件**
202
203- 获取相册管理模块photoAccessHelper实例。
204- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
205
206**开发步骤**
207
2081. 设置获取视频相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.VIDEO。
2092. 调用PhotoAccessHelper.getAlbums接口获取视频相册。
210
211```ts
212import { photoAccessHelper } from '@kit.MediaLibraryKit';
213
214async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
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/arkts-apis-photoAccessHelper-AbsAlbum.md#getassets-1)接口获取视频相册对象中的视频资源。
229
230**前提条件**
231
232- 获取相册管理模块photoAccessHelper实例。
233- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
234
235下面以获取视频相册中的一个视频为例。
236
237**开发步骤**
238
2391. 先[获取视频相册对象](#获取视频相册对象)。
2402. 建立视频检索条件，用于获取视频。
2413. 调用Album.getAssets接口获取视频资源。
2424. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一个视频。
243
244```ts
245import { dataSharePredicates } from '@kit.ArkData';
246import { photoAccessHelper } from '@kit.MediaLibraryKit';
247
248async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
249  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
250  let fetchOptions: photoAccessHelper.FetchOptions = {
251    fetchColumns: [],
252    predicates: predicates
253  };
254
255  try {
256    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
257    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
258    console.info('get video album successfully, albumUri: ' + album.albumUri);
259
260    let videoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
261    let photoAsset: photoAccessHelper.PhotoAsset = await videoFetchResult.getFirstObject();
262    console.info('video album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
263    videoFetchResult.close();
264    albumFetchResult.close();
265  } catch (err) {
266    console.error('video failed with err: ' + err);
267  }
268}
269```
270
271<!--Del-->
272## 截屏和录屏相册（仅向系统应用开放）
273
274截屏和录屏相册属于系统相册，用户文件中属于截屏和录屏的媒体文件会自动加入到截屏和录屏相册中。
275
276### 获取截屏和录屏相册对象
277
278通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getalbums-2)接口获取截屏和录屏相册对象。
279
280**前提条件**
281
282- 获取相册管理模块photoAccessHelper实例。
283- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
284
285**开发步骤**
286
2871. 设置获取截屏和录屏相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.SCREENSHOT。
2882. 调用PhotoAccessHelper.getAlbums接口获取截屏和录屏相册。
289
290```ts
291import { photoAccessHelper } from '@kit.MediaLibraryKit';
292
293async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
294  try {
295    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
296    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
297    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
298    fetchResult.close();
299  } catch (err) {
300    console.error('get screenshot album failed with err: ' + err);
301  }
302}
303```
304
305### 获取截屏和录屏相册中的媒体资源
306
307先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-AbsAlbum.md#getassets-1)接口获取截屏和录屏相册对象中的媒体资源。
308
309**前提条件**
310
311- 获取相册管理模块photoAccessHelper实例。
312- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
313
314下面以获取截屏和录屏相册中的一个媒体资源为例。
315
316**开发步骤**
317
3181. 先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。
3192. 建立检索条件，用于获取媒体资源。
3203. 调用Album.getAssets接口获取媒体资源。
3214. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一个媒体资源。
322
323```ts
324import { dataSharePredicates } from '@kit.ArkData';
325import { photoAccessHelper } from '@kit.MediaLibraryKit';
326
327async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
328  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
329  let fetchOptions: photoAccessHelper.FetchOptions = {
330    fetchColumns: [],
331    predicates: predicates
332  };
333
334  try {
335    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
336    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
337    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
338
339    let screenshotFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
340    let photoAsset: photoAccessHelper.PhotoAsset = await screenshotFetchResult.getFirstObject();
341    console.info('screenshot album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
342    screenshotFetchResult.close();
343    albumFetchResult.close();
344  } catch (err) {
345    console.error('screenshot album failed with err: ' + err);
346  }
347}
348```
349<!--DelEnd-->
350