• 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通过[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)接口创建用户相册。
16
17待创建的相册名参数规格为：
18
19- 相册名字符串长度为1~255。
20- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
21- 英文字符大小写不敏感。
22- 相册名不允许重名。
23
24**前提条件**
25
26- 获取相册管理模块photoAccessHelper实例。
27- 申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'。
28
29下面以创建一个用户相册为例。
30
31**开发步骤**
32
331. 设置相册名。
342. 调用MediaAlbumChangeRequest.createAlbumRequest接口创建相册变更请求。
353. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
36
37```ts
38import photoAccessHelper from '@ohos.file.photoAccessHelper';
39const context = getContext(this);
40let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
41
42async function example() {
43  try {
44    let albumName = 'albumName';
45    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
46    await phAccessHelper.applyChanges(albumChangeRequest);
47    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
48    console.info('create album successfully, album name: ' + album.albumName + ' uri: ' + album.albumUri);
49  } catch (err) {
50    console.error('create album failed with err: ' + err);
51  }
52}
53```
54
55## 获取用户相册
56
57通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取用户相册。
58
59**前提条件**
60
61- 获取相册管理模块photoAccessHelper实例。
62- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'。
63
64下面以获取一个相册名为'albumName'的用户相册为例。
65
66**开发步骤**
67
681. 建立检索条件，用于获取用户相册。
692. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
703. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
71
72```ts
73import dataSharePredicates from '@ohos.data.dataSharePredicates';
74import photoAccessHelper from '@ohos.file.photoAccessHelper';
75const context = getContext(this);
76let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
77
78async function example() {
79  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
80  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
81  predicates.equalTo(albumName, 'albumName');
82  let fetchOptions: photoAccessHelper.FetchOptions = {
83    fetchColumns: [],
84    predicates: predicates
85  };
86
87  try {
88    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
89    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
90    console.info('getAlbums successfully, albumName: ' + album.albumName);
91    fetchResult.close();
92  } catch (err) {
93    console.error('getAlbums failed with err: ' + err);
94  }
95}
96```
97
98## 重命名用户相册
99
100重命名用户相册修改的是相册的Album.albumName属性。
101
102调用[MediaAlbumChangeRequest.setAlbumName](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#setalbumname11)重命名用户相册后再通过[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)更新到数据库中完成修改。
103
104在重命名用户相册之前，需要先获取相册对象，可以通过[FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult)中的接口获取对应位置的用户相册。
105
106重命名的相册名参数规格为：
107
108- 相册名字符串长度为1~255。
109- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
110- 英文字符大小写不敏感。
111- 相册名不允许重名。
112
113**前提条件**
114
115- 获取相册管理模块photoAccessHelper实例。
116- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
117
118下面以将一个相册名为'albumName'的用户相册重命名为例。
119
120**开发步骤**
121
1221. 建立检索条件，用于获取用户相册。
1232. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1243. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
1254. 调用MediaAlbumChangeRequest.setAlbumName接口设置新的相册名。
1265. 调用PhotoAccessHelper.applyChanges接口将修改的相册属性更新到数据中完成修改。
127
128```ts
129import dataSharePredicates from '@ohos.data.dataSharePredicates';
130import photoAccessHelper from '@ohos.file.photoAccessHelper';
131const context = getContext(this);
132let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
133
134async function example() {
135  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
136  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
137  predicates.equalTo(albumName, 'albumName');
138  let fetchOptions: photoAccessHelper.FetchOptions = {
139    fetchColumns: [],
140    predicates: predicates
141  };
142
143  try {
144    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
145    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
146    console.info('getAlbums successfully, albumName: ' + album.albumName);
147    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
148    let newAlbumName: string = 'newAlbumName';
149    albumChangeRequest.setAlbumName(newAlbumName);
150    await phAccessHelper.applyChanges(albumChangeRequest);
151    console.info('setAlbumName successfully, new albumName: ' + album.albumName);
152    fetchResult.close();
153  } catch (err) {
154    console.error('setAlbumName failed with err: ' + err);
155  }
156}
157```
158
159## 添加图片和视频到用户相册中
160
161先[获取用户相册](#获取用户相册)对象和需要添加到相册中的图片或视频的对象数组，然后调用[MediaAlbumChangeRequest.addAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口往用户相册中添加图片或视频。
162
163**前提条件**
164
165- 获取相册管理模块photoAccessHelper实例。
166- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
167
168下面以将往相册名为'albumName'的用户相册中添加一张图片为例。
169
170**开发步骤**
171
1721. 建立相册检索条件，用于获取用户相册。
1732. 建立图片检索条件，用于获取图片。
1743. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1754. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject)接口获取第一个用户相册。
1765. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets)接口获取图片资源。
1776. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject)接口获取第一张图片。
1787. 调用MediaAlbumChangeRequest.addAssets接口往用户相册中添加图片。
1798. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
180
181```ts
182import dataSharePredicates from '@ohos.data.dataSharePredicates';
183import photoAccessHelper from '@ohos.file.photoAccessHelper';
184const context = getContext(this);
185let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
186
187async function example() {
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/js-apis-photoAccessHelper.md#getassets-3)接口获取用户相册中的图片资源。
224
225**前提条件**
226
227- 获取相册管理模块photoAccessHelper实例。
228- 申请相册管理模块权限'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/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
2385. 调用Album.getAssets接口获取用户相册中的图片资源。
2396. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
240
241```ts
242import dataSharePredicates from '@ohos.data.dataSharePredicates';
243import photoAccessHelper from '@ohos.file.photoAccessHelper';
244const context = getContext(this);
245let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
246
247async function example() {
248  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
249  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
250  albumPredicates.equalTo(albumName, 'albumName');
251  let albumFetchOptions: photoAccessHelper.FetchOptions = {
252    fetchColumns: [],
253    predicates: albumPredicates
254  };
255
256  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
257  let photoFetchOptions: photoAccessHelper.FetchOptions = {
258    fetchColumns: [],
259    predicates: photoPredicates
260  };
261
262  try {
263    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
264    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
265    console.info('getAlbums successfully, albumName: ' + album.albumName);
266    let photoFetchResult = await album.getAssets(photoFetchOptions);
267    let photoAsset = await photoFetchResult.getFirstObject();
268    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
269    albumFetchResult.close();
270    photoFetchResult.close();
271  } catch (err) {
272    console.error('album getAssets failed with err: ' + err);
273  }
274}
275```
276
277## 从用户相册中移除图片和视频
278
279先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取用户相册中的资源。
280
281选择其中要移除的资源，然后调用[MediaAlbumChangeRequest.removeAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#removeassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口移除。
282
283**前提条件**
284
285- 获取相册管理模块photoAccessHelper实例。
286- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
287
288下面以将往相册名为'albumName'的用户相册中移除一张图片为例。
289
290**开发步骤**
291
2921. 建立相册检索条件，用于获取用户相册。
2932. 建立图片检索条件，用于获取图片。
2943. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
2954. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
2965. 调用Album.getAssets接口获取图片资源。
2976. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
2987. 调用MediaAlbumChangeRequest.removeAssets接口从用户相册中移除图片。
2998. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
300
301```ts
302import dataSharePredicates from '@ohos.data.dataSharePredicates';
303import photoAccessHelper from '@ohos.file.photoAccessHelper';
304const context = getContext(this);
305let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
306
307async function example() {
308  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
309  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
310  albumPredicates.equalTo(albumName, 'albumName');
311  let albumFetchOptions: photoAccessHelper.FetchOptions = {
312    fetchColumns: [],
313    predicates: albumPredicates
314  };
315
316  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
317  let photoFetchOptions: photoAccessHelper.FetchOptions = {
318    fetchColumns: [],
319    predicates: photoPredicates
320  };
321
322  try {
323    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
324    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
325    console.info('getAlbums successfully, albumName: ' + album.albumName);
326    let photoFetchResult = await album.getAssets(photoFetchOptions);
327    let photoAsset = await photoFetchResult.getFirstObject();
328    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
329    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
330    albumChangeRequest.removeAssets([photoAsset]);
331    await phAccessHelper.applyChanges(albumChangeRequest);
332    console.info('succeed to remove ' + photoAsset.displayName + ' from ' + album.albumName);
333    albumFetchResult.close();
334    photoFetchResult.close();
335  } catch (err) {
336    console.error('removeAssets failed with err: ' + err);
337  }
338}
339```
340
341## 删除用户相册（仅向系统应用开放）
342
343先[获取用户相册](#获取用户相册)对象，然后调用[MediaAlbumChangeRequest.deleteAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#deletealbums11)删除用户相册。
344
345**前提条件**
346
347- 获取相册管理模块photoAccessHelper实例。
348- 申请相册管理模块权限'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
349
350下面以删除一个相册名为'albumName'的用户相册为例。
351
352**开发步骤**
353
3541. 建立检索条件，用于获取用户相册。
3552. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
3563. 调用FetchResult.getFirstObject接口获取第一个用户相册。
3574. 调用MediaAlbumChangeRequest.deleteAlbums接口删除第一个用户相册。
358
359```ts
360import dataSharePredicates from '@ohos.data.dataSharePredicates';
361import photoAccessHelper from '@ohos.file.photoAccessHelper';
362const context = getContext(this);
363let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
364
365async function example() {
366  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
367  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
368  predicates.equalTo(albumName, 'albumName');
369  let fetchOptions: photoAccessHelper.FetchOptions = {
370    fetchColumns: [],
371    predicates: predicates
372  };
373
374  try {
375    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
376    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
377    console.info('getAlbums successfully, albumName: ' + album.albumName);
378    await photoAccessHelper.MediaAlbumChangeRequest.deleteAlbums(context, [album]);
379    fetchResult.close();
380  } catch (err) {
381    console.error('deleteAlbums failed with err: ' + err);
382  }
383}
384```
385