1# @ohos.file.sendablePhotoAccessHelper (基于Sendable对象的相册管理模块) 2 3该模块基于[Sendable](../../arkts-utils/arkts-sendable.md)对象，提供相册管理模块能力，包括创建相册以及访问、修改相册中的媒体数据信息等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { sendablePhotoAccessHelper } from '@kit.MediaLibraryKit'; 13``` 14 15## sendablePhotoAccessHelper.getPhotoAccessHelper 16 17getPhotoAccessHelper(context: Context): PhotoAccessHelper 18 19获取相册管理模块的实例，用于访问和修改相册中的媒体文件。 20 21**模型约束**： 此接口仅可在Stage模型下使用。 22 23**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 24 25**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------- | ------------------------------------------------------------ | ---- | -------------------------- | 31| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 32 33**返回值：** 34 35| 类型 | 说明 | 36| --------------------------------------- | :------------------- | 37| [PhotoAccessHelper](#photoaccesshelper) | 相册管理模块的实例。 | 38 39**错误码：** 40 41接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 42 43| 错误码ID | 错误信息 | 44| -------- | ------------------------------------------------------------ | 45| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 46 47**示例：** 48 49```ts 50// 此处获取的phAccessHelper实例为全局对象，后续使用到phAccessHelper的地方默认为使用此处获取的对象，如未添加此段代码报phAccessHelper未定义的错误请自行添加。 51// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext 52import { common } from '@kit.AbilityKit'; 53let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 54let phAccessHelper = sendablePhotoAccessHelper.getPhotoAccessHelper(context); 55``` 56 57## PhotoAccessHelper 58 59### getAssets 60 61getAssets(options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>> 62 63获取图片和视频资源，使用Promise方式返回结果。 64 65**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 66 67**需要权限**：ohos.permission.READ_IMAGEVIDEO 68 69对于未申请'ohos.permission.READ_IMAGEVIDEO'权限的应用，可以通过picker的方式调用该接口来查询指定uri对应的图片或视频资源，详情请参考[开发指南](../../media/medialibrary/photoAccessHelper-photoviewpicker.md#指定uri获取图片或视频资源)。 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| ------- | --------------------------------------------------------- | ---- | -------------------- | 75| options | [photoAccessHelper.FetchOptions](js-apis-photoAccessHelper.md#fetchoptions) | 是 | 图片和视频检索选项。 | 76 77**返回值：** 78 79| 类型 | 说明 | 80| ------------------------------------------------------------ | --------------------------------------- | 81| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise对象，返回图片和视频数据结果集。 | 82 83**错误码：** 84 85接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 86 87| 错误码ID | 错误信息 | 88| -------- | ------------------------------------------------------------ | 89| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 90| 201 | Permission denied. | 91| 14000011 | Internal system error. | 92 93**示例：** 94 95<!--code_no_check--> 96```ts 97import { dataSharePredicates } from '@kit.ArkData'; 98import { photoAccessHelper } from '@kit.MediaLibraryKit'; 99 100async function example() { 101 console.info('getAssets'); 102 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 103 let fetchOptions: photoAccessHelper.FetchOptions = { 104 fetchColumns: [], 105 predicates: predicates 106 }; 107 try { 108 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 109 if (fetchResult !== undefined) { 110 console.info('fetchResult success'); 111 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 112 if (photoAsset !== undefined) { 113 console.info('photoAsset.displayName :' + photoAsset.displayName); 114 } 115 } 116 } catch (err) { 117 console.error(`getAssets failed, error: ${err.code}, ${err.message}`); 118 } 119} 120``` 121 122### getBurstAssets 123 124getBurstAssets(burstKey: string, options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>> 125 126获取连拍照片资源，使用Promise方式返回结果。 127 128**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 129 130**需要权限**：ohos.permission.READ_IMAGEVIDEO 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 136| burstKey | string | 是 | 一组连拍照片的唯一标识：uuid(可传入[PhotoKeys](js-apis-photoAccessHelper.md#photokeys)的BURST_KEY)。字符串长度为36。| 137| options | [photoAccessHelper.FetchOptions](js-apis-photoAccessHelper.md#fetchoptions) | 是 | 连拍照片检索选项。 | 138 139**返回值：** 140 141| 类型 | 说明 | 142| ------------------------------------------------------------ | ------------------------------------- | 143| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise对象，返回连拍照片数据结果集。 | 144 145**错误码：** 146 147接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 148 149| 错误码ID | 错误信息 | 150| -------- | ------------------------------------------------------------ | 151| 201 | Permission denied. | 152| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 153| 14000011 | Internal system error. | 154 155**示例：** 156 157<!--code_no_check--> 158```ts 159import { photoAccessHelper } from '@kit.MediaLibraryKit'; 160import { dataSharePredicates } from '@kit.ArkData'; 161 162async function example() { 163 console.info('getBurstAssets'); 164 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 165 let fetchOption: photoAccessHelper.FetchOptions = { 166 fetchColumns: [], 167 predicates: predicates 168 }; 169 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 170 let photoAssetList: Array<sendablePhotoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects(); 171 let photoAsset: sendablePhotoAccessHelper.PhotoAsset; 172 // burstKey为36位的uuid，可以根据photoAccessHelper.PhotoKeys获取。 173 for(photoAsset of photoAssetList){ 174 let burstKey: string = photoAccessHelper.PhotoKeys.BURST_KEY.toString(); 175 let photoAccessBurstKey: photoAccessHelper.MemberType = photoAsset.get(burstKey).toString(); 176 try { 177 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await 178 phAccessHelper.getBurstAssets(photoAccessBurstKey, fetchOption); 179 if (fetchResult !== undefined) { 180 console.info('fetchResult success'); 181 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 182 if (photoAsset !== undefined) { 183 console.info('photoAsset.displayName :' + photoAsset.displayName); 184 } 185 } 186 } catch (err) { 187 console.error(`getBurstAssets failed, error: ${err.code}, ${err.message}`); 188 } 189 } 190} 191``` 192 193### createAsset 194 195createAsset(photoType: PhotoType, extension: string, options?: photoAccessHelper.CreateOptions): Promise<string> 196 197指定待创建的文件类型、后缀和创建选项，创建图片或视频资源，使用Promise方式返回结果。 198 199此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考[开发指南](../../media/medialibrary/photoAccessHelper-savebutton.md)。 200 201**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 202 203**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 204 205**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 206 207**参数：** 208 209| 参数名 | 类型 | 必填 | 说明 | 210| --------- | ----------------------------------------------------------- | ---- | ------------------------------------ | 211| photoType | [PhotoType](#phototype) | 是 | 创建的文件类型，IMAGE或者VIDEO类型。 | 212| extension | string | 是 | 文件名后缀参数，例如：'jpg'。字符串长度为1~255。 | 213| options | [photoAccessHelper.CreateOptions](js-apis-photoAccessHelper.md#createoptions) | 否 | 创建选项，例如{title: 'testPhoto'}。 | 214 215**返回值：** 216 217| 类型 | 说明 | 218| --------------------- | ---------------------------------------- | 219| Promise<string> | Promise对象，返回创建的图片和视频的uri。 | 220 221**错误码：** 222 223接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 224 225| 错误码ID | 错误信息 | 226| -------- | ------------------------------------------------------------ | 227| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 228| 201 | Permission denied. | 229| 14000011 | Internal system error. | 230 231**示例：** 232 233<!--code_no_check--> 234```ts 235import { photoAccessHelper } from '@kit.MediaLibraryKit'; 236 237async function example() { 238 console.info('createAssetDemo'); 239 try { 240 let photoType: sendablePhotoAccessHelper.PhotoType = sendablePhotoAccessHelper.PhotoType.IMAGE; 241 let extension: string = 'jpg'; 242 let options: photoAccessHelper.CreateOptions = { 243 title: 'testPhoto' 244 } 245 let uri: string = await phAccessHelper.createAsset(photoType, extension, options); 246 console.info('createAsset uri' + uri); 247 console.info('createAsset successfully'); 248 } catch (err) { 249 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 250 } 251} 252``` 253 254### getAlbums 255 256getAlbums(type: AlbumType, subtype: AlbumSubtype, options?: photoAccessHelper.FetchOptions): Promise<FetchResult<Album>> 257 258根据检索选项和相册类型获取相册，使用Promise方式返回结果。 259 260获取相册前需先保证相册存在。 261 262**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 263 264**需要权限**：ohos.permission.READ_IMAGEVIDEO 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| ------- | --------------------------------------------------------- | ---- | -------------------------------------- | 270| type | [AlbumType](#albumtype) | 是 | 相册类型。 | 271| subtype | [AlbumSubtype](#albumsubtype) | 是 | 相册子类型。 | 272| options | [photoAccessHelper.FetchOptions](js-apis-photoAccessHelper.md#fetchoptions) | 否 | 检索选项，不填时默认根据相册类型检索。 | 273 274**返回值：** 275 276| 类型 | 说明 | 277| ------------------------------------------------------------ | ----------------------------------- | 278| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise对象，返回获取相册的结果集。 | 279 280**错误码：** 281 282接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 283 284| 错误码ID | 错误信息 | 285| -------- | ------------------------------------------------------------ | 286| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 287| 201 | Permission denied. | 288| 14000011 | Internal system error. | 289 290**示例：** 291 292<!--code_no_check--> 293```ts 294import { dataSharePredicates } from '@kit.ArkData'; 295import { BusinessError } from '@kit.BasicServicesKit'; 296import { photoAccessHelper } from '@kit.MediaLibraryKit'; 297 298async function example() { 299 // 示例代码中为获取相册名为newAlbumName的相册。 300 console.info('getAlbumsDemo'); 301 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 302 predicates.equalTo('album_name', 'newAlbumName'); 303 let fetchOptions: photoAccessHelper.FetchOptions = { 304 fetchColumns: [], 305 predicates: predicates 306 }; 307 phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions).then( async (fetchResult) => { 308 if (fetchResult === undefined) { 309 console.error('getAlbumsPromise fetchResult is undefined'); 310 return; 311 } 312 let album: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject(); 313 console.info('getAlbumsPromise successfully, albumName: ' + album.albumName); 314 fetchResult.close(); 315 }).catch((err: BusinessError) => { 316 console.error(`getAlbumsPromise failed with err: ${err.code}, ${err.message}`); 317 }); 318} 319``` 320 321### getAlbums 322 323getAlbums(options: photoAccessHelper.FetchOptions): Promise<FetchResult<Album>> 324 325根据检索选项获取相册，使用Promise方式返回结果。 326 327获取相册前需先保证相册存在。 328 329**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 330 331**需要权限**：ohos.permission.READ_IMAGEVIDEO 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| ------- | --------------------------------------------------------- | ---- | -------- | 337| options | [photoAccessHelper.FetchOptions](js-apis-photoAccessHelper.md#fetchoptions) | 是 | 检索选项。 | 338 339**返回值：** 340 341| 类型 | 说明 | 342| ------------------------------------------------------------ | ----------------------------------- | 343| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise对象，返回获取相册的结果集。 | 344 345**错误码：** 346 347接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 348 349| 错误码ID | 错误信息 | 350| -------- | ------------------------------------------------------------ | 351| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 352| 201 | Permission denied. | 353| 14000011 | Internal system error. | 354 355**示例：** 356 357<!--code_no_check--> 358```ts 359import { dataSharePredicates } from '@kit.ArkData'; 360import { BusinessError } from '@kit.BasicServicesKit'; 361import { photoAccessHelper } from '@kit.MediaLibraryKit'; 362 363async function example() { 364 // 示例代码中为获取相册名为newAlbumName的相册。 365 console.info('getAlbumsDemo'); 366 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 367 predicates.equalTo('album_name', 'newAlbumName'); 368 let fetchOptions: photoAccessHelper.FetchOptions = { 369 fetchColumns: [], 370 predicates: predicates 371 }; 372 phAccessHelper.getAlbums(fetchOptions).then( async (fetchResult) => { 373 if (fetchResult === undefined) { 374 console.error('getAlbumsPromise fetchResult is undefined'); 375 return; 376 } 377 let album: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject(); 378 console.info('getAlbumsPromise successfully, albumName: ' + album.albumName); 379 fetchResult.close(); 380 }).catch((err: BusinessError) => { 381 console.error(`getAlbumsPromise failed with err: ${err.code}, ${err.message}`); 382 }); 383} 384``` 385 386### release 387 388release(): Promise<void> 389 390释放PhotoAccessHelper实例，使用Promise方式返回结果。 391当后续不需要使用PhotoAccessHelper 实例中的方法时调用。 392 393**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 394 395**返回值：** 396 397| 类型 | 说明 | 398| ------------------- | ----------------------- | 399| Promise<void> | Promise对象，返回void。 | 400 401**错误码：** 402 403接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 404 405| 错误码ID | 错误信息 | 406| -------- | ------------------------------------------------------------ | 407| 14000011 | Internal system error. | 408 409**示例：** 410 411<!--code_no_check--> 412```ts 413async function example() { 414 console.info('releaseDemo'); 415 try { 416 console.info('use function...'); 417 } catch (err) { 418 console.error(`function error ...`); 419 }finally{ 420 try{ 421 phAccessHelper?.release(); 422 console.info(`release success`); 423 } catch(e){ 424 console.error(`release error :${e}`); 425 } 426 } 427} 428``` 429 430## PhotoAsset 431 432提供封装文件属性的方法。 433 434### 属性 435 436**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 437 438| 名称 | 类型 | 只读 | 可选 | 说明 | 439| ----------- | ----------------------- | ---- | ---- | ------------------------------------------------------------ | 440| uri<sup>12+</sup> | string | 是 | 否 | 媒体文件资源uri（如：file://media/Photo/1/IMG_datetime_0001/displayName.jpg），详情参见用户文件uri介绍中的[媒体文件uri](../../file-management/user-file-uri-intro.md#媒体文件uri)。 | 441| photoType<sup>12+</sup> | [PhotoType](#phototype) | 是 | 否 | 媒体文件类型。 | 442| displayName<sup>12+</sup> | string | 是 | 否 | 显示文件名，包含后缀名。字符串长度为1~255。 | 443 444### convertToPhotoAsset 445 446convertToPhotoAsset(): photoAccessHelper.PhotoAsset 447 448将Sendable类型PhotoAsset转换为非Sendable类型PhotoAsset。 449 450**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 451 452**返回值：** 453 454| 类型 | 说明 | 455| ---------------------------- | ------------------------------------------------------------ | 456| photoAccessHelper.PhotoAsset | 返回非Sendable类型的[PhotoAsset](js-apis-photoAccessHelper.md#photoasset)。 | 457 458**错误码：** 459 460接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 461 462| 错误码ID | 错误信息 | 463| -------- | ------------------------------------------------------------ | 464| 201 | Permission denied. | 465| 14000011 | Internal system error. | 466 467**示例：** 468 469<!--code_no_check--> 470```ts 471import { dataSharePredicates } from '@kit.ArkData'; 472import { photoAccessHelper } from '@kit.MediaLibraryKit'; 473 474async function example() { 475 console.info('convertToPhotoAssetDemo'); 476 try { 477 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 478 let fetchOption: photoAccessHelper.FetchOptions = { 479 fetchColumns: ['title'], 480 predicates: predicates 481 }; 482 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 483 let sendablePhotoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 484 let photoAsset: photoAccessHelper.PhotoAsset = sendablePhotoAsset.convertToPhotoAsset(); 485 console.log(`get no sendable uri success : ${photoAsset.uri}`); 486 } catch (err) { 487 console.error(`convertToPhotoAsset failed. error: ${err.code}, ${err.message}`); 488 } 489} 490``` 491 492### get 493 494get(member: string): photoAccessHelper.MemberType 495 496获取PhotoAsset成员参数。 497 498**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 499 500**参数：** 501 502| 参数名 | 类型 | 必填 | 说明 | 503| ------ | ------ | ---- | ------------------------------------------------------------ | 504| member | string | 是 | 成员参数名称，在get时，除了'uri'、'media_type'、'subtype'和'display_name'四个属性之外，其他的属性都需要在fetchColumns中填入需要get的[PhotoKeys](js-apis-photoAccessHelper.md#photokeys)，例如：get title属性fetchColumns: ['title']。 | 505 506**返回值：** 507 508| 类型 | 说明 | 509| ----------------------------------------------------- | ---------------------------- | 510| [photoAccessHelper.MemberType](js-apis-photoAccessHelper.md#membertype) | 获取PhotoAsset成员参数的值。 | 511 512**错误码：** 513 514接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 515 516| 错误码ID | 错误信息 | 517| -------- | ------------------------------------------------------------ | 518| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 519 520**示例：** 521 522<!--code_no_check--> 523```ts 524import { dataSharePredicates } from '@kit.ArkData'; 525import { photoAccessHelper } from '@kit.MediaLibraryKit'; 526 527async function example() { 528 console.info('photoAssetGetDemo'); 529 try { 530 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 531 let fetchOption: photoAccessHelper.FetchOptions = { 532 fetchColumns: ['title'], 533 predicates: predicates 534 }; 535 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 536 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 537 let title: photoAccessHelper.PhotoKeys = photoAccessHelper.PhotoKeys.TITLE; 538 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title.toString()); 539 console.info('photoAsset Get photoAssetTitle = ', photoAssetTitle); 540 } catch (err) { 541 console.error(`get failed. error: ${err.code}, ${err.message}`); 542 } 543} 544``` 545 546### set 547 548set(member: string, value: string): void 549 550设置PhotoAsset成员参数。 551 552**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 553 554**参数：** 555 556| 参数名 | 类型 | 必填 | 说明 | 557| ------ | ------ | ---- | ------------------------------------------------------------ | 558| member | string | 是 | 成员参数名称例如：[PhotoKeys](js-apis-photoAccessHelper.md#photokeys).TITLE。字符串长度为1~255。 | 559| value | string | 是 | 设置成员参数名称，只能修改[PhotoKeys](js-apis-photoAccessHelper.md#photokeys).TITLE的值。title的参数规格为：<br>- 不应包含扩展名。<br>- 文件名字符串长度为1~255（资产文件名为标题+扩展名）。<br>- 不允许出现非法字符，包括：. \ / : * ? " ' ` < > \| { } [ ] | 560 561**错误码：** 562 563接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 564 565| 错误码ID | 错误信息 | 566| -------- | ------------------------------------------------------------ | 567| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 568 569**示例：** 570 571<!--code_no_check--> 572```ts 573import { dataSharePredicates } from '@kit.ArkData'; 574import { photoAccessHelper } from '@kit.MediaLibraryKit'; 575 576async function example() { 577 console.info('photoAssetSetDemo'); 578 try { 579 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 580 let fetchOption: photoAccessHelper.FetchOptions = { 581 fetchColumns: ['title'], 582 predicates: predicates 583 }; 584 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 585 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 586 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 587 photoAsset.set(title, 'newTitle'); 588 } catch (err) { 589 console.error(`set failed. error: ${err.code}, ${err.message}`); 590 } 591} 592``` 593 594### commitModify 595 596commitModify(): Promise<void> 597 598修改文件的元数据，使用Promise方式返回异步结果。 599 600**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 601 602**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 603 604**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 605 606**返回值：** 607 608| 类型 | 说明 | 609| ------------------- | ----------------------- | 610| Promise<void> | Promise对象，返回void。 | 611 612**错误码：** 613 614接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 615 616| 错误码ID | 错误信息 | 617| -------- | ------------------------------------------------------------ | 618| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 619| 201 | Permission denied. | 620| 14000011 | Internal system error. | 621 622**示例：** 623 624<!--code_no_check--> 625```ts 626import { dataSharePredicates } from '@kit.ArkData'; 627import { photoAccessHelper } from '@kit.MediaLibraryKit'; 628 629async function example() { 630 console.info('commitModifyDemo'); 631 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 632 let fetchOption: photoAccessHelper.FetchOptions = { 633 fetchColumns: ['title'], 634 predicates: predicates 635 }; 636 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 637 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 638 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 639 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 640 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 641 photoAsset.set(title, 'newTitle3'); 642 try { 643 await photoAsset.commitModify(); 644 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 645 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 646 } catch (err) { 647 console.error(`commitModify failed. error: ${err.code}, ${err.message}`); 648 } 649} 650``` 651 652### getThumbnail 653 654getThumbnail(size?: image.Size): Promise<image.PixelMap> 655 656获取文件的缩略图，传入缩略图尺寸，使用Promise方式返回异步结果。 657 658**需要权限**：ohos.permission.READ_IMAGEVIDEO 659 660**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 661 662**参数：** 663 664| 参数名 | 类型 | 必填 | 说明 | 665| ------ | ----------------------------------------------------- | ---- | ------------ | 666| size | [image.Size](../apis-image-kit/js-apis-image.md#size) | 否 | 缩略图尺寸。 | 667 668**返回值：** 669 670| 类型 | 说明 | 671| ------------------------------------------------------------ | ----------------------------------- | 672| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象，返回缩略图的PixelMap。 | 673 674**错误码：** 675 676接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 677 678| 错误码ID | 错误信息 | 679| -------- | ------------------------------------------------------------ | 680| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 681| 201 | Permission denied. | 682| 14000011 | Internal system error. | 683 684**示例：** 685 686<!--code_no_check--> 687```ts 688import { dataSharePredicates } from '@kit.ArkData'; 689import { image } from '@kit.ImageKit'; 690import { BusinessError } from '@kit.BasicServicesKit'; 691import { photoAccessHelper } from '@kit.MediaLibraryKit'; 692 693async function example() { 694 console.info('getThumbnailDemo'); 695 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 696 let fetchOption: photoAccessHelper.FetchOptions = { 697 fetchColumns: [], 698 predicates: predicates 699 }; 700 let size: image.Size = { width: 720, height: 720 }; 701 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 702 let asset = await fetchResult.getFirstObject(); 703 console.info('asset displayName = ', asset.displayName); 704 asset.getThumbnail(size).then((pixelMap) => { 705 console.info('getThumbnail successful ' + pixelMap); 706 }).catch((err: BusinessError) => { 707 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 708 }); 709} 710``` 711 712## FetchResult 713 714文件检索结果集。 715 716### getCount 717 718getCount(): number 719 720获取文件检索结果中的文件总数。 721 722**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 723 724**返回值：** 725 726| 类型 | 说明 | 727| ------ | ------------------ | 728| number | 检索到的文件总数。 | 729 730**错误码：** 731 732接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 733 734| 错误码ID | 错误信息 | 735| -------- | ------------------------------------------------------------ | 736| 14000011 | Internal system error. | 737 738**示例：** 739 740<!--code_no_check--> 741```ts 742import { dataSharePredicates } from '@kit.ArkData'; 743import { photoAccessHelper } from '@kit.MediaLibraryKit'; 744 745async function example() { 746 console.info('getCountDemo'); 747 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 748 let fetchOption: photoAccessHelper.FetchOptions = { 749 fetchColumns: [], 750 predicates: predicates 751 }; 752 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 753 let fetchCount = fetchResult.getCount(); 754 console.info('fetchCount = ', fetchCount); 755} 756``` 757 758### isAfterLast 759 760isAfterLast(): boolean 761 762检查结果集是否指向最后一行。 763 764**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 765 766**返回值：** 767 768| 类型 | 说明 | 769| ------- | ----------------------------------------------------------- | 770| boolean | 当读到最后一条记录后，后续没有记录返回true，否则返回false。 | 771 772**错误码：** 773 774接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 775 776| 错误码ID | 错误信息 | 777| -------- | ------------------------------------------------------------ | 778| 14000011 | Internal system error. | 779 780**示例：** 781 782<!--code_no_check--> 783```ts 784import { dataSharePredicates } from '@kit.ArkData'; 785import { photoAccessHelper } from '@kit.MediaLibraryKit'; 786 787async function example() { 788 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 789 let fetchOption: photoAccessHelper.FetchOptions = { 790 fetchColumns: [], 791 predicates: predicates 792 }; 793 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 794 let fetchCount = fetchResult.getCount(); 795 console.info('count:' + fetchCount); 796 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getLastObject(); 797 if (fetchResult.isAfterLast()) { 798 console.info('photoAsset isAfterLast displayName = ', photoAsset.displayName); 799 } else { 800 console.info('photoAsset not isAfterLast.'); 801 } 802} 803``` 804 805### close 806 807close(): void 808 809释放FetchResult实例并使其失效。无法调用其他方法。 810 811**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 812 813**错误码：** 814 815接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 816 817| 错误码ID | 错误信息 | 818| -------- | ------------------------------------------------------------ | 819| 14000011 | Internal system error. | 820 821**示例：** 822 823<!--code_no_check--> 824```ts 825import { dataSharePredicates } from '@kit.ArkData'; 826import { photoAccessHelper } from '@kit.MediaLibraryKit'; 827 828async function example() { 829 console.info('fetchResultCloseDemo'); 830 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 831 let fetchOption: photoAccessHelper.FetchOptions = { 832 fetchColumns: [], 833 predicates: predicates 834 }; 835 try { 836 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 837 fetchResult.close(); 838 console.info('close succeed.'); 839 } catch (err) { 840 console.error(`close fail. error: ${err.code}, ${err.message}`); 841 } 842} 843``` 844 845### getFirstObject 846 847getFirstObject(): Promise<T> 848 849获取文件检索结果中的第一个文件资产。此方法使用Promise方式来异步返回。 850 851**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 852 853**返回值：** 854 855| 类型 | 说明 | 856| ---------------- | ------------------------------------- | 857| Promise<T> | Promise对象，返回结果集中第一个对象。 | 858 859**错误码：** 860 861接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 862 863| 错误码ID | 错误信息 | 864| -------- | ------------------------------------------------------------ | 865| 14000011 | Internal system error. | 866 867**示例：** 868 869<!--code_no_check--> 870```ts 871import { dataSharePredicates } from '@kit.ArkData'; 872import { photoAccessHelper } from '@kit.MediaLibraryKit'; 873 874async function example() { 875 console.info('getFirstObjectDemo'); 876 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 877 let fetchOption: photoAccessHelper.FetchOptions = { 878 fetchColumns: [], 879 predicates: predicates 880 }; 881 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 882 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 883 console.info('photoAsset displayName: ', photoAsset.displayName); 884} 885``` 886 887### getNextObject 888 889getNextObject(): Promise<T> 890 891获取文件检索结果中的下一个文件资产。此方法使用Promise方式来异步返回。 892在调用此方法之前，必须使用[isAfterLast()](#isafterlast)来检查当前位置是否为最后一行。 893 894**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 895 896**返回值：** 897 898| 类型 | 说明 | 899| ---------------- | ------------------------------------- | 900| Promise<T> | Promise对象，返回结果集中下一个对象。 | 901 902**错误码：** 903 904接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 905 906| 错误码ID | 错误信息 | 907| -------- | ------------------------------------------------------------ | 908| 14000011 | Internal system error. | 909 910**示例：** 911 912<!--code_no_check--> 913```ts 914import { dataSharePredicates } from '@kit.ArkData'; 915import { photoAccessHelper } from '@kit.MediaLibraryKit'; 916 917async function example() { 918 console.info('getNextObjectDemo'); 919 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 920 let fetchOption: photoAccessHelper.FetchOptions = { 921 fetchColumns: [], 922 predicates: predicates 923 }; 924 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 925 await fetchResult.getFirstObject(); 926 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getNextObject(); 927 console.info('photoAsset displayName: ', photoAsset.displayName); 928} 929``` 930 931### getLastObject 932 933getLastObject(): Promise<T> 934 935获取文件检索结果中的最后一个文件资产。此方法使用Promise方式来返回。 936 937**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 938 939**返回值：** 940 941| 类型 | 说明 | 942| ---------------- | --------------------------------------- | 943| Promise<T> | Promise对象，返回结果集中最后一个对象。 | 944 945**错误码：** 946 947接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 948 949| 错误码ID | 错误信息 | 950| -------- | ------------------------------------------------------------ | 951| 14000011 | Internal system error. | 952 953**示例：** 954 955<!--code_no_check--> 956```ts 957import { dataSharePredicates } from '@kit.ArkData'; 958import { photoAccessHelper } from '@kit.MediaLibraryKit'; 959 960async function example() { 961 console.info('getLastObjectDemo'); 962 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 963 let fetchOption: photoAccessHelper.FetchOptions = { 964 fetchColumns: [], 965 predicates: predicates 966 }; 967 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 968 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getLastObject(); 969 console.info('photoAsset displayName: ', photoAsset.displayName); 970} 971``` 972 973### getObjectByPosition 974 975getObjectByPosition(index: number): Promise<T> 976 977获取文件检索结果中具有指定索引的文件资产。此方法使用Promise形式返回文件Asset。 978 979**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 980 981**参数：** 982 983| 参数名 | 类型 | 必填 | 说明 | 984| ------ | ------ | ---- | ----------------------------- | 985| index | number | 是 | 要获取的文件的索引，从0开始。 | 986 987**返回值：** 988 989| 类型 | 说明 | 990| ---------------- | --------------------------------------------- | 991| Promise<T> | Promise对象，返回结果集中指定索引的一个对象。 | 992 993**错误码：** 994 995接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 996 997| 错误码ID | 错误信息 | 998| -------- | ------------------------------------------------------------ | 999| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1000| 14000011 | Internal system error. | 1001 1002**示例：** 1003 1004<!--code_no_check--> 1005```ts 1006import { dataSharePredicates } from '@kit.ArkData'; 1007import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1008 1009async function example() { 1010 console.info('getObjectByPositionDemo'); 1011 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1012 let fetchOption: photoAccessHelper.FetchOptions = { 1013 fetchColumns: [], 1014 predicates: predicates 1015 }; 1016 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1017 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getObjectByPosition(0); 1018 console.info('photoAsset displayName: ', photoAsset.displayName); 1019} 1020``` 1021 1022### getAllObjects 1023 1024getAllObjects(): Promise<Array<T>> 1025 1026获取文件检索结果中的所有文件资产。此方法使用Promise方式来异步返回。 1027 1028**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1029 1030**返回值：** 1031 1032| 类型 | 说明 | 1033| ----------------------------- | ------------------------------------------- | 1034| Promise<Array<T>> | Promise对象，返回结果集中所有文件资产数组。 | 1035 1036**错误码：** 1037 1038接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1039 1040| 错误码ID | 错误信息 | 1041| -------- | ------------------------------------------------------------ | 1042| 14000011 | Internal system error. | 1043 1044**示例：** 1045 1046<!--code_no_check--> 1047```ts 1048import { dataSharePredicates } from '@kit.ArkData'; 1049import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1050 1051async function example() { 1052 console.info('getAllObjectDemo'); 1053 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1054 let fetchOption: photoAccessHelper.FetchOptions = { 1055 fetchColumns: [], 1056 predicates: predicates 1057 }; 1058 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1059 let photoAssetList: Array<sendablePhotoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects(); 1060 console.info('photoAssetList length: ', photoAssetList.length); 1061} 1062``` 1063 1064## Album 1065 1066实体相册 1067 1068### 属性 1069 1070**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1071 1072| 名称 | 类型 | 只读 | 可选 | 说明 | 1073| ------------ | ----------------------------- | ---------------------------- | ---- | ---------------- | 1074| albumType | [AlbumType](#albumtype) | 是 | 否 | 相册类型。 | 1075| albumSubtype | [AlbumSubtype](#albumsubtype) | 是 | 否 | 相册子类型。 | 1076| albumName | string | 用户相册可写，预置相册不可写 | 否 | 相册名称。 | 1077| albumUri | string | 是 | 否 | 相册Uri。 | 1078| count | number | 是 | 否 | 相册中文件数量。 | 1079| coverUri | string | 是 | 否 | 封面文件Uri。 | 1080| imageCount | number | 是 | 是 | 相册中图片数量。 | 1081| videoCount | number | 是 | 是 | 相册中视频数量。 | 1082 1083### convertToPhotoAlbum 1084 1085convertToPhotoAlbum(): photoAccessHelper.Album 1086 1087将Sendable类型Album转换为非Sendable类型Album。 1088 1089**需要权限**：ohos.permission.READ_IMAGEVIDEO 1090 1091**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1092 1093| 类型 | 说明 | 1094| ----------------------- | --------------------------------------------------------- | 1095| [photoAccessHelper.Album](js-apis-photoAccessHelper.md#album) | 非Sendable类型Album。 | 1096 1097**错误码：** 1098 1099接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1100 1101| 错误码ID | 错误信息 | 1102| -------- | ------------------------------------------------------------ | 1103| 201 | Permission denied. | 1104| 14000011 | Internal system error. | 1105 1106**示例：** 1107 1108<!--code_no_check--> 1109```ts 1110import { dataSharePredicates } from '@kit.ArkData'; 1111import { BusinessError } from '@kit.BasicServicesKit'; 1112import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1113 1114async function example() { 1115 console.info('convertToPhotoAlbumDemo'); 1116 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1117 let albumFetchOptions: photoAccessHelper.FetchOptions = { 1118 fetchColumns: [], 1119 predicates: predicates 1120 }; 1121 let fetchOption: photoAccessHelper.FetchOptions = { 1122 fetchColumns: [], 1123 predicates: predicates 1124 }; 1125 let albumList: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.Album> = await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 1126 let sendableAlbum: sendablePhotoAccessHelper.Album = await albumList.getFirstObject(); 1127 let album: photoAccessHelper.Album = sendableAlbum.convertToPhotoAlbum(); 1128 album.getAssets(fetchOption).then((albumFetchResult) => { 1129 console.info('convertToPhotoAlbum successfully, getCount: ' + albumFetchResult.getCount()); 1130 }).catch((err: BusinessError) => { 1131 console.error(`convertToPhotoAlbum failed with error: ${err.code}, ${err.message}`); 1132 }); 1133} 1134``` 1135 1136### getAssets 1137 1138getAssets(options: FetchOptions): Promise<FetchResult<PhotoAsset>> 1139 1140获取相册中的文件。该方法使用Promise来返回文件。 1141 1142**需要权限**：ohos.permission.READ_IMAGEVIDEO 1143 1144**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1145 1146**参数：** 1147 1148| 参数名 | 类型 | 必填 | 说明 | 1149| ------- | --------------------------------------------------------- | ---- | ---------- | 1150| options | [FetchOptions](js-apis-photoAccessHelper.md#fetchoptions) | 是 | 检索选项。 | 1151 1152**返回值：** 1153 1154| 类型 | 说明 | 1155| ------------------------------------------------------------ | --------------------------------------- | 1156| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise对象，返回图片和视频数据结果集。 | 1157 1158**错误码：** 1159 1160接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1161 1162| 错误码ID | 错误信息 | 1163| -------- | ------------------------------------------------------------ | 1164| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1165| 201 | Permission denied. | 1166| 13900020 | Invalid argument. | 1167| 14000011 | Internal system error. | 1168 1169**示例：** 1170 1171<!--code_no_check--> 1172```ts 1173import { dataSharePredicates } from '@kit.ArkData'; 1174import { BusinessError } from '@kit.BasicServicesKit'; 1175import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1176 1177async function example() { 1178 console.info('albumGetAssetsDemoPromise'); 1179 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1180 let albumFetchOptions: photoAccessHelper.FetchOptions = { 1181 fetchColumns: [], 1182 predicates: predicates 1183 }; 1184 let fetchOption: photoAccessHelper.FetchOptions = { 1185 fetchColumns: [], 1186 predicates: predicates 1187 }; 1188 let albumList: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.Album> = await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 1189 let album: sendablePhotoAccessHelper.Album = await albumList.getFirstObject(); 1190 album.getAssets(fetchOption).then((albumFetchResult) => { 1191 console.info('album getAssets successfully, getCount: ' + albumFetchResult.getCount()); 1192 }).catch((err: BusinessError) => { 1193 console.error(`album getAssets failed with error: ${err.code}, ${err.message}`); 1194 }); 1195} 1196``` 1197 1198### commitModify 1199 1200commitModify(): Promise<void> 1201 1202更新相册属性修改到数据库中。该方法使用Promise来返回结果。 1203 1204**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 1205 1206**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1207 1208**返回值：** 1209 1210| 类型 | 说明 | 1211| ------------------- | ----------------------- | 1212| Promise<void> | Promise对象，返回void。 | 1213 1214**错误码：** 1215 1216接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1217 1218| 错误码ID | 错误信息 | 1219| -------- | ------------------------------------------------------------ | 1220| 201 | Permission denied. | 1221| 14000011 | Internal system error. | 1222 1223**示例：** 1224 1225<!--code_no_check--> 1226```ts 1227import { dataSharePredicates } from '@kit.ArkData'; 1228import { BusinessError } from '@kit.BasicServicesKit'; 1229import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1230 1231async function example() { 1232 console.info('albumCommitModifyDemo'); 1233 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1234 let albumFetchOptions: photoAccessHelper.FetchOptions = { 1235 fetchColumns: [], 1236 predicates: predicates 1237 }; 1238 let albumList: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.Album> = await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 1239 let album: sendablePhotoAccessHelper.Album = await albumList.getFirstObject(); 1240 album.albumName = 'hello'; 1241 album.commitModify().then(() => { 1242 console.info('commitModify successfully'); 1243 }).catch((err: BusinessError) => { 1244 console.error(`commitModify failed with error: ${err.code}, ${err.message}`); 1245 }); 1246} 1247``` 1248 1249## PhotoType 1250 1251枚举，媒体文件类型。 1252 1253**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1254 1255**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1256 1257| 名称 | 值 | 说明 | 1258| ----- | ---- | ------ | 1259| IMAGE | 1 | 图片。 | 1260| VIDEO | 2 | 视频。 | 1261 1262## PhotoSubtype<sup>14+</sup> 1263 1264枚举，不同[PhotoAsset](#photoasset)的类型。 1265 1266**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1267 1268**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1269 1270| 名称 | 值 | 说明 | 1271| ----- | ---- | ---- | 1272| DEFAULT | 0 | 默认照片类型。 | 1273| MOVING_PHOTO | 3 | 动态照片文件类型。 | 1274| BURST | 4 | 连拍照片文件类型。 | 1275 1276## DynamicRangeType<sup>14+</sup> 1277 1278枚举，媒体文件的动态范围类型。 1279 1280**系统能力**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1281 1282| 名称 | 值 | 说明 | 1283| ----- | ---- | ---- | 1284| SDR | 0 | 标准动态范围类型。| 1285| HDR | 1 | 高动态范围类型。 | 1286 1287## AlbumType 1288 1289枚举，相册类型，表示是用户相册还是系统预置相册。 1290 1291**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1292 1293| 名称 | 值 | 说明 | 1294| ------ | ---- | -------------- | 1295| USER | 0 | 用户相册。 | 1296| SYSTEM | 1024 | 系统预置相册。 | 1297 1298## AlbumSubtype 1299 1300枚举，相册子类型，表示具体的相册类型。 1301 1302**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1303 1304| 名称 | 值 | 说明 | 1305| ------------- | ---------- | ---------- | 1306| USER\_GENERIC | 1 | 用户相册。 | 1307| FAVORITE | 1025 | 收藏夹。 | 1308| VIDEO | 1026 | 视频相册。 | 1309| IMAGE | 1031 | 图片相册。 | 1310| ANY | 2147483647 | 任意相册。 | 1311
