• 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<!--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';
40import { common } from '@kit.AbilityKit';
41
42// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
43let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
44let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
45
46async function example() {
47  try {
48    let albumName = 'albumName';
49    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName);
50    await phAccessHelper.applyChanges(albumChangeRequest);
51    let album: photoAccessHelper.Album = albumChangeRequest.getAlbum();
52    console.info('create album successfully, album name: ' + album.albumName + ' uri: ' + album.albumUri);
53  } catch (err) {
54    console.error('create album failed with err: ' + err);
55  }
56}
57```
58<!--DelEnd-->
59
60## 获取用户相册
61
62通过[PhotoAccessHelper.getAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getalbums-2)接口获取用户相册。
63
64**前提条件**
65
66- 获取相册管理模块photoAccessHelper实例。
67- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
68
69下面以获取一个相册名为'albumName'的用户相册为例。
70
71**开发步骤**
72
731. 建立检索条件，用于获取用户相册。
742. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
753. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
76
77```ts
78import { dataSharePredicates } from '@kit.ArkData';
79import { photoAccessHelper } from '@kit.MediaLibraryKit';
80import { common } from '@kit.AbilityKit';
81
82// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
83let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
84let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
85
86async function example() {
87  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
88  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
89  predicates.equalTo(albumName, 'albumName');
90  let fetchOptions: photoAccessHelper.FetchOptions = {
91    fetchColumns: [],
92    predicates: predicates
93  };
94
95  try {
96    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
97    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
98    console.info('getAlbums successfully, albumName: ' + album.albumName);
99    fetchResult.close();
100  } catch (err) {
101    console.error('getAlbums failed with err: ' + err);
102  }
103}
104```
105
106## 重命名用户相册
107
108重命名用户相册修改的是相册的Album.albumName属性。
109
110调用[MediaAlbumChangeRequest.setAlbumName](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#setalbumname11)重命名用户相册后再通过[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)更新到数据库中完成修改。
111
112在重命名用户相册之前，需要先获取相册对象，可以通过[FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult)中的接口获取对应位置的用户相册。
113
114重命名的相册名参数规格为：
115
116- 相册名字符串长度为1~255。
117- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ]
118- 英文字符大小写不敏感。
119- 相册名不允许重名。
120
121**前提条件**
122
123- 获取相册管理模块photoAccessHelper实例。
124- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
125
126下面以将一个相册名为'albumName'的用户相册重命名为例。
127
128**开发步骤**
129
1301. 建立检索条件，用于获取用户相册。
1312. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1323. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
1334. 调用MediaAlbumChangeRequest.setAlbumName接口设置新的相册名。
1345. 调用PhotoAccessHelper.applyChanges接口将修改的相册属性更新到数据中完成修改。
135
136```ts
137import { dataSharePredicates } from '@kit.ArkData';
138import { photoAccessHelper } from '@kit.MediaLibraryKit';
139import { common } from '@kit.AbilityKit';
140
141// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
142let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
143let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
144
145async function example() {
146  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
147  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
148  predicates.equalTo(albumName, 'albumName');
149  let fetchOptions: photoAccessHelper.FetchOptions = {
150    fetchColumns: [],
151    predicates: predicates
152  };
153
154  try {
155    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
156    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
157    console.info('getAlbums successfully, albumName: ' + album.albumName);
158    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
159    let newAlbumName: string = 'newAlbumName';
160    albumChangeRequest.setAlbumName(newAlbumName);
161    await phAccessHelper.applyChanges(albumChangeRequest);
162    console.info('setAlbumName successfully, new albumName: ' + album.albumName);
163    fetchResult.close();
164  } catch (err) {
165    console.error('setAlbumName failed with err: ' + err);
166  }
167}
168```
169
170## 添加图片和视频到用户相册中
171
172先[获取用户相册](#获取用户相册)对象和需要添加到相册中的图片或视频的对象数组，然后调用[MediaAlbumChangeRequest.addAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口往用户相册中添加图片或视频。
173
174**前提条件**
175
176- 获取相册管理模块photoAccessHelper实例。
177- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
178
179下面以将往相册名为'albumName'的用户相册中添加一张图片为例。
180
181**开发步骤**
182
1831. 建立相册检索条件，用于获取用户相册。
1842. 建立图片检索条件，用于获取图片。
1853. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
1864. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject)接口获取第一个用户相册。
1875. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets)接口获取图片资源。
1886. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject)接口获取第一张图片。
1897. 调用MediaAlbumChangeRequest.addAssets接口往用户相册中添加图片。
1908. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
191
192```ts
193import { dataSharePredicates } from '@kit.ArkData';
194import { photoAccessHelper } from '@kit.MediaLibraryKit';
195import { common } from '@kit.AbilityKit';
196
197// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
198let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
199let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
200
201async function example() {
202  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
203  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
204  albumPredicates.equalTo(albumName, 'albumName');
205  let albumFetchOptions: photoAccessHelper.FetchOptions = {
206    fetchColumns: [],
207    predicates: albumPredicates
208  };
209
210  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
211  let photoFetchOptions: photoAccessHelper.FetchOptions = {
212    fetchColumns: [],
213    predicates: photoPredicates
214  };
215
216  try {
217    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
218    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
219    console.info('getAlbums successfully, albumName: ' + album.albumName);
220    let photoFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(photoFetchOptions);
221    let photoAsset: photoAccessHelper.PhotoAsset = await photoFetchResult.getFirstObject();
222    console.info('getAssets successfully, albumName: ' + photoAsset.displayName);
223    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
224    albumChangeRequest.addAssets([photoAsset]);
225    await phAccessHelper.applyChanges(albumChangeRequest);
226    console.info('succeed to add ' + photoAsset.displayName + ' to ' + album.albumName);
227    albumFetchResult.close();
228    photoFetchResult.close();
229  } catch (err) {
230    console.error('addAssets failed with err: ' + err);
231  }
232}
233```
234
235## 获取用户相册中的图片和视频
236
237先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取用户相册中的图片资源。
238
239**前提条件**
240
241- 获取相册管理模块photoAccessHelper实例。
242- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
243
244下面以获取相册名为'albumName'的用户相册中的一张图片为例。
245
246**开发步骤**
247
2481. 建立相册检索条件，用于获取用户相册。
2492. 建立图片检索条件，用于获取图片。
2503. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
2514. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
2525. 调用Album.getAssets接口获取用户相册中的图片资源。
2536. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
254
255```ts
256import { dataSharePredicates } from '@kit.ArkData';
257import { photoAccessHelper } from '@kit.MediaLibraryKit';
258import { common } from '@kit.AbilityKit';
259
260// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
261let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
262let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
263
264async function example() {
265  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
266  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
267  albumPredicates.equalTo(albumName, 'albumName');
268  let albumFetchOptions: photoAccessHelper.FetchOptions = {
269    fetchColumns: [],
270    predicates: albumPredicates
271  };
272
273  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
274  let photoFetchOptions: photoAccessHelper.FetchOptions = {
275    fetchColumns: [],
276    predicates: photoPredicates
277  };
278
279  try {
280    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
281    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
282    console.info('getAlbums successfully, albumName: ' + album.albumName);
283    let photoFetchResult = await album.getAssets(photoFetchOptions);
284    let photoAsset = await photoFetchResult.getFirstObject();
285    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
286    albumFetchResult.close();
287    photoFetchResult.close();
288  } catch (err) {
289    console.error('album getAssets failed with err: ' + err);
290  }
291}
292```
293
294## 从用户相册中移除图片和视频
295
296先[获取用户相册](#获取用户相册)对象，然后调用[Album.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-3)接口获取用户相册中的资源。
297
298选择其中要移除的资源，然后调用[MediaAlbumChangeRequest.removeAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#removeassets11)和[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口移除。
299
300**前提条件**
301
302- 获取相册管理模块photoAccessHelper实例。
303- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
304
305下面以将往相册名为'albumName'的用户相册中移除一张图片为例。
306
307**开发步骤**
308
3091. 建立相册检索条件，用于获取用户相册。
3102. 建立图片检索条件，用于获取图片。
3113. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
3124. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一个用户相册。
3135. 调用Album.getAssets接口获取图片资源。
3146. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
3157. 调用MediaAlbumChangeRequest.removeAssets接口从用户相册中移除图片。
3168. 调用PhotoAccessHelper.applyChanges接口提交相册变更请求。
317
318```ts
319import { dataSharePredicates } from '@kit.ArkData';
320import { photoAccessHelper } from '@kit.MediaLibraryKit';
321import { common } from '@kit.AbilityKit';
322
323// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
324let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
325let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
326
327async function example() {
328  let albumPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
329  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
330  albumPredicates.equalTo(albumName, 'albumName');
331  let albumFetchOptions: photoAccessHelper.FetchOptions = {
332    fetchColumns: [],
333    predicates: albumPredicates
334  };
335
336  let photoPredicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
337  let photoFetchOptions: photoAccessHelper.FetchOptions = {
338    fetchColumns: [],
339    predicates: photoPredicates
340  };
341
342  try {
343    let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions);
344    let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject();
345    console.info('getAlbums successfully, albumName: ' + album.albumName);
346    let photoFetchResult = await album.getAssets(photoFetchOptions);
347    let photoAsset = await photoFetchResult.getFirstObject();
348    console.info('album getAssets successfully, albumName: ' + photoAsset.displayName);
349    let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album);
350    albumChangeRequest.removeAssets([photoAsset]);
351    await phAccessHelper.applyChanges(albumChangeRequest);
352    console.info('succeed to remove ' + photoAsset.displayName + ' from ' + album.albumName);
353    albumFetchResult.close();
354    photoFetchResult.close();
355  } catch (err) {
356    console.error('removeAssets failed with err: ' + err);
357  }
358}
359```
360
361<!--Del-->
362## 删除用户相册（仅向系统应用开放）
363
364先[获取用户相册](#获取用户相册)对象，然后调用[MediaAlbumChangeRequest.deleteAlbums](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#deletealbums11)删除用户相册。
365
366**前提条件**
367
368- 获取相册管理模块photoAccessHelper实例。
369- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'和'ohos.permission.WRITE_IMAGEVIDEO'。
370
371下面以删除一个相册名为'albumName'的用户相册为例。
372
373**开发步骤**
374
3751. 建立检索条件，用于获取用户相册。
3762. 调用PhotoAccessHelper.getAlbums接口获取用户相册资源。
3773. 调用FetchResult.getFirstObject接口获取第一个用户相册。
3784. 调用MediaAlbumChangeRequest.deleteAlbums接口删除第一个用户相册。
379
380```ts
381import { dataSharePredicates } from '@kit.ArkData';
382import { photoAccessHelper } from '@kit.MediaLibraryKit';
383import { common } from '@kit.AbilityKit';
384
385// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
386let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
387let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
388
389async function example() {
390  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
391  let albumName: photoAccessHelper.AlbumKeys = photoAccessHelper.AlbumKeys.ALBUM_NAME;
392  predicates.equalTo(albumName, 'albumName');
393  let fetchOptions: photoAccessHelper.FetchOptions = {
394    fetchColumns: [],
395    predicates: predicates
396  };
397
398  try {
399    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions);
400    let album: photoAccessHelper.Album = await fetchResult.getFirstObject();
401    console.info('getAlbums successfully, albumName: ' + album.albumName);
402    await photoAccessHelper.MediaAlbumChangeRequest.deleteAlbums(context, [album]);
403    fetchResult.close();
404  } catch (err) {
405    console.error('deleteAlbums failed with err: ' + err);
406  }
407}
408```
409<!--DelEnd-->
410