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