• 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<!--Del-->
20## 创建用户相册（仅向系统应用开放）
21
22通过[MediaAlbumChangeRequest.createAlbumRequest](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#createalbumrequest11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11)接口创建用户相册。
23
24待创建的相册名参数规格为：
25
26- 相册名字符串长度为1~255。
27- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
28- 英文字符大小写不敏感。
29- 相册名不允许重名。
30
31**前提条件**
32
33- 获取相册管理模块photoAccessHelper实例。
34- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.WRITE_IMAGEVIDEO'。
35
36下面以创建一个用户相册为例。
37
38**开发步骤**
39
401. 设置相册名。
412. 调用MediaAlbumChangeRequest.createAlbumRequest接口创建相册变更请求。
423. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
43
44```ts
45import { photoAccessHelper } from '@kit.MediaLibraryKit';
46
47async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper, context: Context) {
48  try {
49    let albumName = 'albumName';
50    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
51    await phAccessHelper.applyChanges(albumChangeRequest);
52    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
53    console.info('create album successfully, album name: ' + album.albumName + ' uri: ' + album.albumUri);
54  } catch (err) {
55    console.error('create album failed with err: ' + err);
56  }
57}
58```
59<!--DelEnd-->
60
61## 获取用户相册
62
63通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getalbums-2)接口获取用户相册。
64
65**前提条件**
66
67- 获取相册管理模块photoAccessHelper实例。
68- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
69
70下面以获取一个相册名为'albumName'的用户相册为例。
71
72**开发步骤**
73
741. 建立检索条件，用于获取用户相册。
752. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
763. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一个用户相册。
77
78```ts
79import { dataSharePredicates } from '@kit.ArkData';
80import { photoAccessHelper } from '@kit.MediaLibraryKit';
81
82async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
83  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
84  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
85  predicates.equalTo(albumName, 'albumName');
86  let fetchOptions: photoAccessHelper.FetchOptions = {
87    fetchColumns: [],
88    predicates: predicates
89  };
90
91  try {
92    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
93    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
94    console.info('getAlbums successfully, albumName: ' + album.albumName);
95    fetchResult.close();
96  } catch (err) {
97    console.error('getAlbums failed with err: ' + err);
98  }
99}
100```
101
102## 重命名用户相册
103
104重命名用户相册时，修改的是相册的Album.albumName属性。
105
106调用[MediaAlbumChangeRequest.setAlbumName](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#setalbumname11)重命名用户相册后再通过[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11)更新到数据库中完成修改。
107
108在重命名用户相册之前，需要先获取相册对象，可以通过[FetchResult](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md)中的接口获取对应位置的用户相册。
109
110重命名相册时，相册名的参数规格为：
111
112- 相册名字符串长度为1~255。
113- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
114- 英文字符大小写不敏感。
115- 相册名不允许重名。
116
117**前提条件**
118
119- 获取相册管理模块photoAccessHelper实例。
120- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
121
122下面以将一个相册名为'albumName'的用户相册重命名为例。
123
124**开发步骤**
125
1261. 建立检索条件，用于获取用户相册。
1272. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1283. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一个用户相册。
1294. 调用MediaAlbumChangeRequest.setAlbumName接口设置新的相册名。
1305. 调用PhotoAccessHelper.applyChanges接口将修改的相册属性更新到数据库中完成修改。
131
132```ts
133import { dataSharePredicates } from '@kit.ArkData';
134import { photoAccessHelper } from '@kit.MediaLibraryKit';
135
136async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
137  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
138  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
139  predicates.equalTo(albumName, 'albumName');
140  let fetchOptions: photoAccessHelper.FetchOptions = {
141    fetchColumns: [],
142    predicates: predicates
143  };
144
145  try {
146    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
147    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
148    console.info('getAlbums successfully, albumName: ' + album.albumName);
149    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
150    let newAlbumName: string = 'newAlbumName';
151    albumChangeRequest.setAlbumName(newAlbumName);
152    await phAccessHelper.applyChanges(albumChangeRequest);
153    console.info('setAlbumName successfully, new albumName: ' + album.albumName);
154    fetchResult.close();
155  } catch (err) {
156    console.error('setAlbumName failed with err: ' + err);
157  }
158}
159```
160
161## 添加图片和视频到用户相册中
162
163先[获取用户相册](#获取用户相册)对象和需要添加到用户相册中的图片或视频的对象数组，然后调用[MediaAlbumChangeRequest.addAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#addassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11)接口往用户相册中添加图片或视频。
164
165**前提条件**
166
167- 获取相册管理模块photoAccessHelper实例。
168- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
169
170下面以将往相册名为'albumName'的用户相册中添加一张图片为例。
171
172**开发步骤**
173
1741. 建立相册检索条件，用于获取用户相册。
1752. 建立图片检索条件，用于获取图片。
1763. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1774. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject)接口获取第一个用户相册。
1785. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets)接口获取图片资源。
1796. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject)接口获取第一张图片。
1807. 调用MediaAlbumChangeRequest.addAssets接口往用户相册中添加图片。
1818. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
182
183```ts
184import { dataSharePredicates } from '@kit.ArkData';
185import { photoAccessHelper } from '@kit.MediaLibraryKit';
186
187async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
188  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
189  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
190  albumPredicates.equalTo(albumName, 'albumName');
191  let albumFetchOptions: photoAccessHelper.FetchOptions = {
192    fetchColumns: [],
193    predicates: albumPredicates
194  };
195
196  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
197  let photoFetchOptions: photoAccessHelper.FetchOptions = {
198    fetchColumns: [],
199    predicates: photoPredicates
200  };
201
202  try {
203    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
204    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
205    console.info('getAlbums successfully, albumName: ' + album.albumName);
206    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(photoFetchOptions);
207    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
208    console.info('getAssets successfully, albumName: ' + photoAsset.displayName);
209    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
210    albumChangeRequest.addAssets([photoAsset]);
211    await phAccessHelper.applyChanges(albumChangeRequest);
212    console.info('succeed to add ' + photoAsset.displayName + ' to ' + album.albumName);
213    albumFetchResult.close();
214    photoFetchResult.close();
215  } catch (err) {
216    console.error('addAssets failed with err: ' + err);
217  }
218}
219```
220
221## 获取用户相册中的图片和视频
222
223先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-AbsAlbum.md#getassets-1)接口获取用户相册中的图片资源。
224
225**前提条件**
226
227- 获取相册管理模块photoAccessHelper实例。
228- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
229
230下面以获取相册名为'albumName'的用户相册中的一张图片为例。
231
232**开发步骤**
233
2341. 建立相册检索条件，用于获取用户相册。
2352. 建立图片检索条件，用于获取图片。
2363. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
2374. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一个用户相册。
2385. 调用Album.getAssets接口获取用户相册中的图片资源。
2396. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一张图片。
240
241```ts
242import { dataSharePredicates } from '@kit.ArkData';
243import { photoAccessHelper } from '@kit.MediaLibraryKit';
244
245async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
246  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
247  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
248  albumPredicates.equalTo(albumName, 'albumName');
249  let albumFetchOptions: photoAccessHelper.FetchOptions = {
250    fetchColumns: [],
251    predicates: albumPredicates
252  };
253
254  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
255  let photoFetchOptions: photoAccessHelper.FetchOptions = {
256    fetchColumns: [],
257    predicates: photoPredicates
258  };
259
260  try {
261    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
262    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
263    console.info('getAlbums successfully, albumName: ' + album.albumName);
264    let photoFetchResult = await album.getAssets(photoFetchOptions);
265    let photoAsset = await photoFetchResult.getFirstObject();
266    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
267    albumFetchResult.close();
268    photoFetchResult.close();
269  } catch (err) {
270    console.error('album getAssets failed with err: ' + err);
271  }
272}
273```
274
275## 从用户相册中移除图片和视频
276
277先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-AbsAlbum.md#getassets-1)接口获取用户相册中的资源。
278
279选择其中要移除的资源，然后调用[MediaAlbumChangeRequest.removeAssets](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#removeassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11)接口移除。
280
281**前提条件**
282
283- 获取相册管理模块photoAccessHelper实例。
284- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
285
286下面以从相册名为'albumName'的用户相册中移除一张图片为例。
287
288**开发步骤**
289
2901. 建立相册检索条件，用于获取用户相册。
2912. 建立图片检索条件，用于获取图片。
2923. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
2934. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一个用户相册。
2945. 调用Album.getAssets接口获取图片资源。
2956. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-FetchResult.md#getfirstobject-1)接口获取第一张图片。
2967. 调用MediaAlbumChangeRequest.removeAssets接口从用户相册中移除图片。
2978. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
298
299```ts
300import { dataSharePredicates } from '@kit.ArkData';
301import { photoAccessHelper } from '@kit.MediaLibraryKit';
302
303async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
304  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
305  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
306  albumPredicates.equalTo(albumName, 'albumName');
307  let albumFetchOptions: photoAccessHelper.FetchOptions = {
308    fetchColumns: [],
309    predicates: albumPredicates
310  };
311
312  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
313  let photoFetchOptions: photoAccessHelper.FetchOptions = {
314    fetchColumns: [],
315    predicates: photoPredicates
316  };
317
318  try {
319    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
320    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
321    console.info('getAlbums successfully, albumName: ' + album.albumName);
322    let photoFetchResult = await album.getAssets(photoFetchOptions);
323    let photoAsset = await photoFetchResult.getFirstObject();
324    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
325    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
326    albumChangeRequest.removeAssets([photoAsset]);
327    await phAccessHelper.applyChanges(albumChangeRequest);
328    console.info('succeed to remove ' + photoAsset.displayName + ' from ' + album.albumName);
329    albumFetchResult.close();
330    photoFetchResult.close();
331  } catch (err) {
332    console.error('removeAssets failed with err: ' + err);
333  }
334}
335```
336
337<!--Del-->
338## 删除用户相册（仅向系统应用开放）
339
340先[获取用户相册](#获取用户相册)对象，然后调用[MediaAlbumChangeRequest.deleteAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#deletealbums11)删除用户相册。
341
342**前提条件**
343
344- 获取相册管理模块photoAccessHelper实例。
345- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
346
347下面以删除一个相册名为'albumName'的用户相册为例。
348
349**开发步骤**
350
3511. 建立检索条件，用于获取用户相册。
3522. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
3533. 调用FetchResult.getFirstObject接口获取第一个用户相册。
3544. 调用MediaAlbumChangeRequest.deleteAlbums接口删除第一个用户相册。
355
356```ts
357import { dataSharePredicates } from '@kit.ArkData';
358import { photoAccessHelper } from '@kit.MediaLibraryKit';
359
360async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper, context: Context) {
361  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
362  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
363  predicates.equalTo(albumName, 'albumName');
364  let fetchOptions: photoAccessHelper.FetchOptions = {
365    fetchColumns: [],
366    predicates: predicates
367  };
368
369  try {
370    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
371    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
372    console.info('getAlbums successfully, albumName: ' + album.albumName);
373    await photoAccessHelper.MediaAlbumChangeRequest.deleteAlbums(context, [album]);
374    fetchResult.close();
375  } catch (err) {
376    console.error('deleteAlbums failed with err: ' + err);
377  }
378}
379```
380<!--DelEnd-->
381