1# Interface (Album) 2<!--Kit: Media Library Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @yixiaoff--> 5<!--Designer: @liweilu1--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12 13Album extends [AbsAlbum](arkts-apis-photoAccessHelper-AbsAlbum.md) 14 15实体相册。 16 17## 导入模块 18 19```ts 20import { photoAccessHelper } from '@kit.MediaLibraryKit'; 21``` 22 23## 属性 24 25**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 26 27| 名称 | 类型 | 只读 | 可选 | 说明 | 28| ------------ | ------ | ---- | ---- | ------- | 29| imageCount<sup>11+</sup> | number | 是 | 是 | 相册中图片数量。| 30| videoCount<sup>11+</sup> | number | 是 | 是 | 相册中视频数量。| 31 32## commitModify 33 34commitModify(callback: AsyncCallback<void>): void 35 36更新相册属性修改到数据库中。该方法使用callback形式来返回结果。 37 38**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 39 40**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| -------- | ------------------------- | ---- | ---------- | 46| callback | AsyncCallback<void> | 是 | callback返回void。 | 47 48**错误码：** 49 50接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 51 52 53| 错误码ID | 错误信息 | 54| -------- | ---------------------------------------- | 55| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 56| 201 | Permission denied. | 57| 13900020 | Invalid argument. | 58| 14000011 | System inner fail. | 59 60**示例：** 61 62phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 63 64```ts 65import { dataSharePredicates } from '@kit.ArkData'; 66 67async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 68 console.info('albumCommitModifyDemo'); 69 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 70 let albumFetchOptions: photoAccessHelper.FetchOptions = { 71 fetchColumns: [], 72 predicates: predicates 73 }; 74 let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 75 let album: photoAccessHelper.Album = await albumList.getFirstObject(); 76 album.albumName = 'hello'; 77 album.commitModify((err) => { 78 if (err !== undefined) { 79 console.error(`commitModify failed with error: ${err.code}, ${err.message}`); 80 } else { 81 console.info('commitModify successfully'); 82 } 83 }); 84} 85``` 86 87## commitModify 88 89commitModify(): Promise<void> 90 91更新相册属性修改到数据库中。该方法使用Promise来返回结果。 92 93**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 94 95**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 96 97**返回值：** 98 99| 类型 | 说明 | 100| ------------------- | ------------ | 101| Promise<void> | Promise对象，返回void。 | 102 103**错误码：** 104 105接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 106 107 108| 错误码ID | 错误信息 | 109| -------- | ---------------------------------------- | 110| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 111| 201 | Permission denied. | 112| 13900020 | Invalid argument. | 113| 14000011 | System inner fail. | 114 115**示例：** 116 117phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 118 119```ts 120import { dataSharePredicates } from '@kit.ArkData'; 121import { BusinessError } from '@kit.BasicServicesKit'; 122 123async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 124 console.info('albumCommitModifyDemo'); 125 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 126 let albumFetchOptions: photoAccessHelper.FetchOptions = { 127 fetchColumns: [], 128 predicates: predicates 129 }; 130 let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 131 let album: photoAccessHelper.Album = await albumList.getFirstObject(); 132 album.albumName = 'hello'; 133 album.commitModify().then(() => { 134 console.info('commitModify successfully'); 135 }).catch((err: BusinessError) => { 136 console.error(`commitModify failed with error: ${err.code}, ${err.message}`); 137 }); 138} 139``` 140 141## addAssets<sup>(deprecated)</sup> 142 143addAssets(assets: Array<PhotoAsset>, callback: AsyncCallback<void>): void 144 145向用户相册中添加图片或视频前，需预置相册和文件资源。此方法通过callback方式返回结果。 146 147> **说明：** 148> 149> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.addAssets](arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#addassets11)替代。 150 151**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 152 153**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 154 155**参数：** 156 157| 参数名 | 类型 | 必填 | 说明 | 158| -------- | ------------------------- | ---- | ---------- | 159| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | 是 | 待添加到相册中的图片或视频数组。 | 160| callback | AsyncCallback<void> | 是 | callback返回void。 | 161 162**错误码：** 163 164接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 165 166 167| 错误码ID | 错误信息 | 168| -------- | ---------------------------------------- | 169| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 170| 201 | Permission denied. | 171| 13900020 | Invalid argument. | 172| 14000011 | System inner fail. | 173 174**示例：** 175 176phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 177 178```ts 179import { dataSharePredicates } from '@kit.ArkData'; 180 181async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 182 try { 183 console.info('addAssetsDemoCallback'); 184 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 185 let fetchOption: photoAccessHelper.FetchOptions = { 186 fetchColumns: [], 187 predicates: predicates 188 }; 189 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 190 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 191 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 192 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 193 album.addAssets([asset], (err) => { 194 if (err === undefined) { 195 console.info('album addAssets successfully'); 196 } else { 197 console.error(`album addAssets failed with error: ${err.code}, ${err.message}`); 198 } 199 }); 200 } catch (err) { 201 console.error(`addAssetsDemoCallback failed with error: ${err.code}, ${err.message}`); 202 } 203} 204``` 205 206## addAssets<sup>(deprecated)</sup> 207 208addAssets(assets: Array<PhotoAsset>): Promise<void> 209 210向用户相册添加图片或视频前，需预置相册和文件资源。此方法通过Promise返回结果。 211 212> **说明：** 213> 214> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.addAssets](arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#addassets11)替代。 215 216**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 217 218**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| -------- | ------------------------- | ---- | ---------- | 224| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | 是 | 待添加到相册中的图片或视频数组。 | 225 226**返回值：** 227 228| 类型 | 说明 | 229| --------------------------------------- | ----------------- | 230|Promise<void> | Promise对象，返回void。 | 231 232**错误码：** 233 234接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 235 236 237| 错误码ID | 错误信息 | 238| -------- | ---------------------------------------- | 239| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 240| 201 | Permission denied. | 241| 13900020 | Invalid argument. | 242| 14000011 | System inner fail. | 243 244**示例：** 245 246phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 247 248```ts 249import { dataSharePredicates } from '@kit.ArkData'; 250import { BusinessError } from '@kit.BasicServicesKit'; 251 252async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 253 try { 254 console.info('addAssetsDemoPromise'); 255 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 256 let fetchOption: photoAccessHelper.FetchOptions = { 257 fetchColumns: [], 258 predicates: predicates 259 }; 260 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 261 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 262 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 263 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 264 album.addAssets([asset]).then(() => { 265 console.info('album addAssets successfully'); 266 }).catch((err: BusinessError) => { 267 console.error(`album addAssets failed with error: ${err.code}, ${err.message}`); 268 }); 269 } catch (err) { 270 console.error(`addAssetsDemoPromise failed with error: ${err.code}, ${err.message}`); 271 } 272} 273``` 274 275## removeAssets<sup>(deprecated)</sup> 276 277removeAssets(assets: Array<PhotoAsset>, callback: AsyncCallback<void>): void 278 279从用户相册移除图片或视频前，需预置相册和文件资源。该方法以callback形式返回结果。 280 281> **说明：** 282> 283> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.removeAssets](arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#removeassets11)替代。 284 285**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 286 287**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 288 289**参数：** 290 291| 参数名 | 类型 | 必填 | 说明 | 292| -------- | ------------------------- | ---- | ---------- | 293| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | 是 | 相册中待移除的图片或视频数组。 | 294| callback | AsyncCallback<void> | 是 | callback返回void。 | 295 296**错误码：** 297 298接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 299 300 301| 错误码ID | 错误信息 | 302| -------- | ---------------------------------------- | 303| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 304| 201 | Permission denied. | 305| 13900020 | Invalid argument. | 306| 14000011 | System inner fail. | 307 308**示例：** 309 310phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 311 312```ts 313import { dataSharePredicates } from '@kit.ArkData'; 314 315async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 316 try { 317 console.info('removeAssetsDemoCallback'); 318 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 319 let fetchOption: photoAccessHelper.FetchOptions = { 320 fetchColumns: [], 321 predicates: predicates 322 }; 323 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 324 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 325 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOption); 326 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 327 album.removeAssets([asset], (err) => { 328 if (err === undefined) { 329 console.info('album removeAssets successfully'); 330 } else { 331 console.error(`album removeAssets failed with error: ${err.code}, ${err.message}`); 332 } 333 }); 334 } catch (err) { 335 console.error(`removeAssetsDemoCallback failed with error: ${err.code}, ${err.message}`); 336 } 337} 338``` 339 340## removeAssets<sup>(deprecated)</sup> 341 342removeAssets(assets: Array<PhotoAsset>): Promise<void> 343 344从用户相册中移除图片或视频前，需预置相册和文件资源。此方法通过Promise返回结果。 345 346> **说明：** 347> 348> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.removeAssets](arkts-apis-photoAccessHelper-MediaAlbumChangeRequest.md#removeassets11)替代。 349 350**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 351 352**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 353 354**参数：** 355 356| 参数名 | 类型 | 必填 | 说明 | 357| -------- | ------------------------- | ---- | ---------- | 358| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | 是 | 相册中待移除的图片或视频数组。 | 359 360**返回值：** 361 362| 类型 | 说明 | 363| --------------------------------------- | ----------------- | 364|Promise<void> | Promise对象，返回void。 | 365 366**错误码：** 367 368接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 369 370 371| 错误码ID | 错误信息 | 372| -------- | ---------------------------------------- | 373| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 374| 201 | Permission denied. | 375| 13900020 | Invalid argument. | 376| 14000011 | System inner fail. | 377 378**示例：** 379 380phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 381 382```ts 383import { dataSharePredicates } from '@kit.ArkData'; 384import { BusinessError } from '@kit.BasicServicesKit'; 385 386async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 387 try { 388 console.info('removeAssetsDemoPromise'); 389 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 390 let fetchOption: photoAccessHelper.FetchOptions = { 391 fetchColumns: [], 392 predicates: predicates 393 }; 394 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 395 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 396 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOption); 397 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 398 album.removeAssets([asset]).then(() => { 399 console.info('album removeAssets successfully'); 400 }).catch((err: BusinessError) => { 401 console.error(`album removeAssets failed with error: ${err.code}, ${err.message}`); 402 }); 403 } catch (err) { 404 console.error(`removeAssetsDemoPromise failed with error: ${err.code}, ${err.message}`); 405 } 406} 407``` 408