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<!--Del-->
14## 创建用户相册（仅向系统应用开放）
15
16通过[MediaAlbumChangeRequest.createAlbumRequest](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#createalbumrequest11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口创建用户相册。
17
18待创建的相册名参数规格为：
19
20- 相册名字符串长度为1~255。
21- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
22- 英文字符大小写不敏感。
23- 相册名不允许重名。
24
25**前提条件**
26
27- 获取相册管理模块photoAccessHelper实例。
28- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.WRITE_IMAGEVIDEO'。
29
30下面以创建一个用户相册为例。
31
32**开发步骤**
33
341. 设置相册名。
352. 调用MediaAlbumChangeRequest.createAlbumRequest接口创建相册变更请求。
363. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
37
38```ts
39import { photoAccessHelper } from '@kit.MediaLibraryKit';
40const context = getContext(this);
41let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
42
43async function example() {
44  try {
45    let albumName = 'albumName';
46    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
47    await phAccessHelper.applyChanges(albumChangeRequest);
48    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
49    console.info('create album successfully, album name: ' + album.albumName + ' uri: ' + album.albumUri);
50  } catch (err) {
51    console.error('create album failed with err: ' + err);
52  }
53}
54```
55<!--DelEnd-->
56
57## 获取用户相册
58
59通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取用户相册。
60
61**前提条件**
62
63- 获取相册管理模块photoAccessHelper实例。
64- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
65
66下面以获取一个相册名为'albumName'的用户相册为例。
67
68**开发步骤**
69
701. 建立检索条件，用于获取用户相册。
712. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
723. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
73
74```ts
75import { dataSharePredicates } from '@kit.ArkData';
76import { photoAccessHelper } from '@kit.MediaLibraryKit';
77const context = getContext(this);
78let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
79
80async function example() {
81  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
82  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
83  predicates.equalTo(albumName, 'albumName');
84  let fetchOptions: photoAccessHelper.FetchOptions = {
85    fetchColumns: [],
86    predicates: predicates
87  };
88
89  try {
90    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
91    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
92    console.info('getAlbums successfully, albumName: ' + album.albumName);
93    fetchResult.close();
94  } catch (err) {
95    console.error('getAlbums failed with err: ' + err);
96  }
97}
98```
99
100## 重命名用户相册
101
102重命名用户相册修改的是相册的Album.albumName属性。
103
104调用[MediaAlbumChangeRequest.setAlbumName](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#setalbumname11)重命名用户相册后再通过[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)更新到数据库中完成修改。
105
106在重命名用户相册之前，需要先获取相册对象，可以通过[FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult)中的接口获取对应位置的用户相册。
107
108重命名的相册名参数规格为：
109
110- 相册名字符串长度为1~255。
111- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
112- 英文字符大小写不敏感。
113- 相册名不允许重名。
114
115**前提条件**
116
117- 获取相册管理模块photoAccessHelper实例。
118- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
119
120下面以将一个相册名为'albumName'的用户相册重命名为例。
121
122**开发步骤**
123
1241. 建立检索条件，用于获取用户相册。
1252. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1263. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
1274. 调用MediaAlbumChangeRequest.setAlbumName接口设置新的相册名。
1285. 调用PhotoAccessHelper.applyChanges接口将修改的相册属性更新到数据中完成修改。
129
130```ts
131import { dataSharePredicates } from '@kit.ArkData';
132import { photoAccessHelper } from '@kit.MediaLibraryKit';
133const context = getContext(this);
134let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
135
136async function example() {
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/js-apis-photoAccessHelper.md#addassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-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/js-apis-photoAccessHelper.md#getfirstobject)接口获取第一个用户相册。
1785. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets)接口获取图片资源。
1796. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject)接口获取第一张图片。
1807. 调用MediaAlbumChangeRequest.addAssets接口往用户相册中添加图片。
1818. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
182
183```ts
184import { dataSharePredicates } from '@kit.ArkData';
185import { photoAccessHelper } from '@kit.MediaLibraryKit';
186const context = getContext(this);
187let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
188
189async function example() {
190  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
191  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
192  albumPredicates.equalTo(albumName, 'albumName');
193  let albumFetchOptions: photoAccessHelper.FetchOptions = {
194    fetchColumns: [],
195    predicates: albumPredicates
196  };
197
198  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
199  let photoFetchOptions: photoAccessHelper.FetchOptions = {
200    fetchColumns: [],
201    predicates: photoPredicates
202  };
203
204  try {
205    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
206    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
207    console.info('getAlbums successfully, albumName: ' + album.albumName);
208    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(photoFetchOptions);
209    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
210    console.info('getAssets successfully, albumName: ' + photoAsset.displayName);
211    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
212    albumChangeRequest.addAssets([photoAsset]);
213    await phAccessHelper.applyChanges(albumChangeRequest);
214    console.info('succeed to add ' + photoAsset.displayName + ' to ' + album.albumName);
215    albumFetchResult.close();
216    photoFetchResult.close();
217  } catch (err) {
218    console.error('addAssets failed with err: ' + err);
219  }
220}
221```
222
223## 获取用户相册中的图片和视频
224
225先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取用户相册中的图片资源。
226
227**前提条件**
228
229- 获取相册管理模块photoAccessHelper实例。
230- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
231
232下面以获取相册名为'albumName'的用户相册中的一张图片为例。
233
234**开发步骤**
235
2361. 建立相册检索条件，用于获取用户相册。
2372. 建立图片检索条件，用于获取图片。
2383. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
2394. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
2405. 调用Album.getAssets接口获取用户相册中的图片资源。
2416. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
242
243```ts
244import { dataSharePredicates } from '@kit.ArkData';
245import { photoAccessHelper } from '@kit.MediaLibraryKit';
246const context = getContext(this);
247let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
248
249async function example() {
250  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
251  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
252  albumPredicates.equalTo(albumName, 'albumName');
253  let albumFetchOptions: photoAccessHelper.FetchOptions = {
254    fetchColumns: [],
255    predicates: albumPredicates
256  };
257
258  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
259  let photoFetchOptions: photoAccessHelper.FetchOptions = {
260    fetchColumns: [],
261    predicates: photoPredicates
262  };
263
264  try {
265    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
266    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
267    console.info('getAlbums successfully, albumName: ' + album.albumName);
268    let photoFetchResult = await album.getAssets(photoFetchOptions);
269    let photoAsset = await photoFetchResult.getFirstObject();
270    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
271    albumFetchResult.close();
272    photoFetchResult.close();
273  } catch (err) {
274    console.error('album getAssets failed with err: ' + err);
275  }
276}
277```
278
279## 从用户相册中移除图片和视频
280
281先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取用户相册中的资源。
282
283选择其中要移除的资源，然后调用[MediaAlbumChangeRequest.removeAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#removeassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口移除。
284
285**前提条件**
286
287- 获取相册管理模块photoAccessHelper实例。
288- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
289
290下面以将往相册名为'albumName'的用户相册中移除一张图片为例。
291
292**开发步骤**
293
2941. 建立相册检索条件，用于获取用户相册。
2952. 建立图片检索条件，用于获取图片。
2963. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
2974. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
2985. 调用Album.getAssets接口获取图片资源。
2996. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
3007. 调用MediaAlbumChangeRequest.removeAssets接口从用户相册中移除图片。
3018. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
302
303```ts
304import { dataSharePredicates } from '@kit.ArkData';
305import { photoAccessHelper } from '@kit.MediaLibraryKit';
306const context = getContext(this);
307let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
308
309async function example() {
310  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
311  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
312  albumPredicates.equalTo(albumName, 'albumName');
313  let albumFetchOptions: photoAccessHelper.FetchOptions = {
314    fetchColumns: [],
315    predicates: albumPredicates
316  };
317
318  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
319  let photoFetchOptions: photoAccessHelper.FetchOptions = {
320    fetchColumns: [],
321    predicates: photoPredicates
322  };
323
324  try {
325    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
326    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
327    console.info('getAlbums successfully, albumName: ' + album.albumName);
328    let photoFetchResult = await album.getAssets(photoFetchOptions);
329    let photoAsset = await photoFetchResult.getFirstObject();
330    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
331    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
332    albumChangeRequest.removeAssets([photoAsset]);
333    await phAccessHelper.applyChanges(albumChangeRequest);
334    console.info('succeed to remove ' + photoAsset.displayName + ' from ' + album.albumName);
335    albumFetchResult.close();
336    photoFetchResult.close();
337  } catch (err) {
338    console.error('removeAssets failed with err: ' + err);
339  }
340}
341```
342
343<!--Del-->
344## 删除用户相册（仅向系统应用开放）
345
346先[获取用户相册](#获取用户相册)对象，然后调用[MediaAlbumChangeRequest.deleteAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#deletealbums11)删除用户相册。
347
348**前提条件**
349
350- 获取相册管理模块photoAccessHelper实例。
351- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
352
353下面以删除一个相册名为'albumName'的用户相册为例。
354
355**开发步骤**
356
3571. 建立检索条件，用于获取用户相册。
3582. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
3593. 调用FetchResult.getFirstObject接口获取第一个用户相册。
3604. 调用MediaAlbumChangeRequest.deleteAlbums接口删除第一个用户相册。
361
362```ts
363import { dataSharePredicates } from '@kit.ArkData';
364import { photoAccessHelper } from '@kit.MediaLibraryKit';
365const context = getContext(this);
366let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
367
368async function example() {
369  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
370  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
371  predicates.equalTo(albumName, 'albumName');
372  let fetchOptions: photoAccessHelper.FetchOptions = {
373    fetchColumns: [],
374    predicates: predicates
375  };
376
377  try {
378    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
379    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
380    console.info('getAlbums successfully, albumName: ' + album.albumName);
381    await photoAccessHelper.MediaAlbumChangeRequest.deleteAlbums(context, [album]);
382    fetchResult.close();
383  } catch (err) {
384    console.error('deleteAlbums failed with err: ' + err);
385  }
386}
387```
388<!--DelEnd-->
389