• 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- [申请相册管理模块权限](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';
33import { common } from '@kit.AbilityKit';
34
35// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
36let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
37let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
38
39async function example() {
40  try {
41    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
42    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
43    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
44    fetchResult.close();
45  } catch (err) {
46    console.error('get favorite album failed with err: ' + err);
47  }
48}
49```
50
51<!--Del-->
52### 收藏图片和视频（仅向系统应用开放）
53
54通过[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)接口将图片或视频设置为收藏。
55
56**前提条件**
57
58- 获取相册管理模块photoAccessHelper实例。
59- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
60
61下面将以收藏一张图片为例。
62
63**开发步骤**
64
651. [获取指定媒体资源](photoAccessHelper-resource-guidelines.md#获取指定媒体资源)。
662. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为收藏。
673. 调用PhotoAccessHelper.applyChanges接口提交收藏图片的变更请求。
68
69```ts
70import { dataSharePredicates } from '@kit.ArkData';
71import { photoAccessHelper } from '@kit.MediaLibraryKit';
72import { common } from '@kit.AbilityKit';
73
74// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
75let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
76let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
77
78async function example() {
79  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
80  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
81  let fetchOptions: photoAccessHelper.FetchOptions = {
82    fetchColumns: [],
83    predicates: predicates
84  };
85
86  try {
87    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
88    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
89    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
90    let favoriteState = true;
91    assetChangeRequest.setFavorite(favoriteState);
92    await phAccessHelper.applyChanges(assetChangeRequest);
93  } catch (err) {
94    console.error('setFavorite failed with err: ' + err);
95  }
96}
97```
98<!--DelEnd-->
99
100### 获取收藏夹中的图片和视频
101
102先[获取收藏夹对象](#获取收藏夹对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取收藏夹中的资源。
103
104**前提条件**
105
106- 获取相册管理模块photoAccessHelper实例。
107- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
108
109下面以获取收藏夹中的一张图片为例。
110
111**开发步骤**
112
1131. [获取收藏夹对象](#获取收藏夹对象)。
1142. 建立图片检索条件，用于获取图片。
1153. 调用Album.getAssets接口获取图片资源。
1164. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
117
118```ts
119import { dataSharePredicates } from '@kit.ArkData';
120import { photoAccessHelper } from '@kit.MediaLibraryKit';
121import { common } from '@kit.AbilityKit';
122
123// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
124let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
125let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
126
127async function example() {
128  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
129  let fetchOptions: photoAccessHelper.FetchOptions = {
130    fetchColumns: [],
131    predicates: predicates
132  };
133
134  try {
135    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
136    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
137    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
138
139    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
140    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
141    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
142    photoFetchResult.close();
143    albumFetchResult.close();
144  } catch (err) {
145    console.error('favorite failed with err: ' + err);
146  }
147}
148```
149
150<!--Del-->
151### 取消收藏图片或视频（仅向系统应用开放）
152
153通过[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)接口将图片或视频取消收藏。
154
155**前提条件**
156
157- 获取相册管理模块photoAccessHelper实例。
158- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
159
160下面以将一张图片取消收藏为例。
161
162**开发步骤**
163
1641. [获取收藏夹中的图片和视频](#获取收藏夹中的图片和视频)。
1652. 调用MediaAssetChangeRequest.setFavorite接口将图片设置为取消收藏。
1663. 调用PhotoAccessHelper.applyChanges接口提交取消收藏图片的变更请求。
167
168
169```ts
170import { dataSharePredicates } from '@kit.ArkData';
171import { photoAccessHelper } from '@kit.MediaLibraryKit';
172import { common } from '@kit.AbilityKit';
173
174// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
175let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
176let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
177
178async function example() {
179  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
180  let fetchOptions: photoAccessHelper.FetchOptions = {
181    fetchColumns: [],
182    predicates: predicates
183  };
184
185  try {
186    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.FAVORITE);
187    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
188    console.info('get favorite album successfully, albumUri: ' + album.albumUri);
189
190    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
191    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
192    console.info('favorite album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
193
194    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
195    let favoriteState = false;
196    assetChangeRequest.setFavorite(favoriteState);
197    await phAccessHelper.applyChanges(assetChangeRequest);
198    photoFetchResult.close();
199    albumFetchResult.close();
200  } catch (err) {
201    console.error('setFavorite failed with err: ' + err);
202  }
203}
204```
205<!--DelEnd-->
206
207## 视频相册
208
209视频相册属于系统相册，用户文件中属于视频类型的媒体文件会自动加入到视频相册中。
210
211### 获取视频相册对象
212
213通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取视频相册对象。
214
215**前提条件**
216
217- 获取相册管理模块photoAccessHelper实例。
218- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
219
220**开发步骤**
221
2221. 设置获取视频相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.VIDEO。
2232. 调用PhotoAccessHelper.getAlbums接口获取视频相册。
224
225```ts
226import { photoAccessHelper } from '@kit.MediaLibraryKit';
227import { common } from '@kit.AbilityKit';
228
229// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
230let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
231let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
232
233async function example() {
234  try {
235    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
236    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
237    console.info('get video album successfully, albumUri: ' + album.albumUri);
238    fetchResult.close();
239  } catch (err) {
240    console.error('get video album failed with err: ' + err);
241  }
242}
243```
244
245### 获取视频相册中的视频
246
247先[获取视频相册对象](#获取视频相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取视频相册对象中的视频资源。
248
249**前提条件**
250
251- 获取相册管理模块photoAccessHelper实例。
252- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
253
254下面以获取视频相册中的一个视频为例。
255
256**开发步骤**
257
2581. 先[获取视频相册对象](#获取视频相册对象)。
2592. 建立视频检索条件，用于获取视频。
2603. 调用Album.getAssets接口获取视频资源。
2614. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个视频。
262
263```ts
264import { dataSharePredicates } from '@kit.ArkData';
265import { photoAccessHelper } from '@kit.MediaLibraryKit';
266import { common } from '@kit.AbilityKit';
267
268// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
269let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
270let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
271
272async function example() {
273  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
274  let fetchOptions: photoAccessHelper.FetchOptions = {
275    fetchColumns: [],
276    predicates: predicates
277  };
278
279  try {
280    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO);
281    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
282    console.info('get video album successfully, albumUri: ' + album.albumUri);
283
284    let videoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
285    let photoAsset: photoAccessHelper.PhotoAsset = await videoFetchResult.getFirstObject();
286    console.info('video album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
287    videoFetchResult.close();
288    albumFetchResult.close();
289  } catch (err) {
290    console.error('video failed with err: ' + err);
291  }
292}
293```
294
295<!--Del-->
296## 截屏和录屏相册（仅向系统应用开放）
297
298截屏和录屏相册属于系统相册，用户文件中属于截屏和录屏的媒体文件会自动加入到截屏和录屏相册中。
299
300### 获取截屏和录屏相册对象
301
302通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取截屏和录屏相册对象。
303
304**前提条件**
305
306- 获取相册管理模块photoAccessHelper实例。
307- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
308
309**开发步骤**
310
3111. 设置获取截屏和录屏相册的参数为photoAccessHelper.AlbumType.SYSTEM和photoAccessHelper.AlbumSubtype.SCREENSHOT。
3122. 调用PhotoAccessHelper.getAlbums接口获取截屏和录屏相册。
313
314```ts
315import { photoAccessHelper } from '@kit.MediaLibraryKit';
316import { common } from '@kit.AbilityKit';
317
318// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
319let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
320let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
321
322async function example() {
323  try {
324    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
325    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
326    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
327    fetchResult.close();
328  } catch (err) {
329    console.error('get screenshot album failed with err: ' + err);
330  }
331}
332```
333
334### 获取截屏和录屏相册中的媒体资源
335
336先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取截屏和录屏相册对象中的媒体资源。
337
338**前提条件**
339
340- 获取相册管理模块photoAccessHelper实例。
341- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
342
343下面以获取截屏和录屏相册中的一个媒体资源为例。
344
345**开发步骤**
346
3471. 先[获取截屏和录屏相册对象](#获取截屏和录屏相册对象)。
3482. 建立检索条件，用于获取媒体资源。
3493. 调用Album.getAssets接口获取媒体资源。
3504. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个媒体资源。
351
352```ts
353import { dataSharePredicates } from '@kit.ArkData';
354import { photoAccessHelper } from '@kit.MediaLibraryKit';
355import { common } from '@kit.AbilityKit';
356
357// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
358let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
359let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
360
361async function example() {
362  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
363  let fetchOptions: photoAccessHelper.FetchOptions = {
364    fetchColumns: [],
365    predicates: predicates
366  };
367
368  try {
369    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.SCREENSHOT);
370    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
371    console.info('get screenshot album successfully, albumUri: ' + album.albumUri);
372
373    let screenshotFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions);
374    let photoAsset: photoAccessHelper.PhotoAsset = await screenshotFetchResult.getFirstObject();
375    console.info('screenshot album getAssets successfully, photoAsset displayName: ' + photoAsset.displayName);
376    screenshotFetchResult.close();
377    albumFetchResult.close();
378  } catch (err) {
379    console.error('screenshot album failed with err: ' + err);
380  }
381}
382```
383<!--DelEnd-->
384