1# @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object) 2<!--Kit: Media Library Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @yixiaoff--> 5<!--SE: @liweilu1--> 6<!--TSE: @xchaosioda--> 7 8The module provides APIs for album management, including creating an album and accessing and modifying media data in an album, based on a [Sendable](../../arkts-utils/arkts-sendable.md) object. 9 10> **NOTE** 11> 12> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 13 14## Modules to Import 15 16```ts 17import { sendablePhotoAccessHelper } from '@kit.MediaLibraryKit'; 18``` 19 20## sendablePhotoAccessHelper.getPhotoAccessHelper 21 22getPhotoAccessHelper(context: Context): PhotoAccessHelper 23 24Obtains a PhotoAccessHelper instance, which can be used for accessing and modifying media files in an album. 25 26**Model restriction**: This API can be used only in the stage model. 27 28**Atomic service API**: This API can be used in atomic services since API version 12. 29 30**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 31 32**Parameters** 33 34| Name | Type | Mandatory| Description | 35| ------- | ------------------------------------------------------------ | ---- | -------------------------- | 36| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Context of the ability instance.| 37 38**Return value** 39 40| Type | Description | 41| --------------------------------------- | :------------------- | 42| [PhotoAccessHelper](#photoaccesshelper) | PhotoAccessHelper instance obtained.| 43 44**Error codes** 45 46For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 47 48| ID| Error Message | 49| -------- | ------------------------------------------------------------ | 50| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 51 52**Example** 53 54```ts 55// The phAccessHelper instance obtained is a global object. It is used by default in subsequent operations. If the code snippet is not added, an error will be reported indicating that phAccessHelper is not defined. 56// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext. 57import { common } from '@kit.AbilityKit'; 58 59@Entry 60@Component 61struct Index { 62 build() { 63 Row() { 64 Button("example").onClick(async () => { 65 let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 66 let phAccessHelper = sendablePhotoAccessHelper.getPhotoAccessHelper(context); 67 }).width('100%') 68 } 69 .height('90%') 70 } 71} 72``` 73 74## PhotoAccessHelper 75 76### getAssets 77 78getAssets(options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>> 79 80Obtains media assets. This API uses a promise to return the result. 81 82**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 83 84**Required permissions**: ohos.permission.READ_IMAGEVIDEO 85 86If the caller does not have the ohos.permission.READ_IMAGEVIDEO permission, use Picker to access the file and then call this API based on the URI obtained by Picker. For details, see [Obtaining an Image or Video by URI](../../media/medialibrary/photoAccessHelper-photoviewpicker.md#obtaining-an-image-or-video-by-uri). 87 88**Parameters** 89 90| Name | Type | Mandatory| Description | 91| ------- | --------------------------------------------------------- | ---- | -------------------- | 92| options | [photoAccessHelper.FetchOptions](arkts-apis-photoAccessHelper-i.md#fetchoptions) | Yes | Retrieval options.| 93 94**Return value** 95 96| Type | Description | 97| ------------------------------------------------------------ | --------------------------------------- | 98| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise used to return the media assets obtained.| 99 100**Error codes** 101 102For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 103 104| ID| Error Message | 105| -------- | ------------------------------------------------------------ | 106| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 107| 201 | Permission denied. | 108| 14000011 | Internal system error. | 109 110**Example** 111 112For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 113 114<!--code_no_check--> 115```ts 116import { dataSharePredicates } from '@kit.ArkData'; 117import { photoAccessHelper } from '@kit.MediaLibraryKit'; 118 119async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 120 console.info('getAssets'); 121 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 122 let fetchOptions: photoAccessHelper.FetchOptions = { 123 fetchColumns: [], 124 predicates: predicates 125 }; 126 try { 127 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 128 if (fetchResult !== undefined) { 129 console.info('fetchResult success'); 130 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 131 if (photoAsset !== undefined) { 132 console.info('photoAsset.displayName :' + photoAsset.displayName); 133 } 134 } 135 } catch (err) { 136 console.error(`getAssets failed, error: ${err.code}, ${err.message}`); 137 } 138} 139``` 140 141### getBurstAssets 142 143getBurstAssets(burstKey: string, options: photoAccessHelper.FetchOptions): Promise<FetchResult<PhotoAsset>> 144 145Obtains burst assets. This API uses a promise to return the result. 146 147**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 148 149**Required permissions**: ohos.permission.READ_IMAGEVIDEO 150 151**Parameters** 152 153| Name | Type | Mandatory| Description | 154| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 155| burstKey | string | Yes | Universally Unique Identifier (UUID) of a group of burst photos, that is, **BURST_KEY** of [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys). The value is a string of 36 characters.| 156| options | [photoAccessHelper.FetchOptions](arkts-apis-photoAccessHelper-i.md#fetchoptions) | Yes | Retrieval options. | 157 158**Return value** 159 160| Type | Description | 161| ------------------------------------------------------------ | ------------------------------------- | 162| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise used to return the result.| 163 164**Error codes** 165 166For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 167 168| ID| Error Message | 169| -------- | ------------------------------------------------------------ | 170| 201 | Permission denied. | 171| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 172| 14000011 | Internal system error. | 173 174**Example** 175 176For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 177 178<!--code_no_check--> 179```ts 180import { photoAccessHelper } from '@kit.MediaLibraryKit'; 181import { dataSharePredicates } from '@kit.ArkData'; 182 183async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 184 console.info('getBurstAssets'); 185 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 186 let fetchOption: photoAccessHelper.FetchOptions = { 187 fetchColumns: [], 188 predicates: predicates 189 }; 190 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 191 let photoAssetList: Array<sendablePhotoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects(); 192 let photoAsset: sendablePhotoAccessHelper.PhotoAsset; 193 // burstKey is a 36-bit UUID, which can be obtained from photoAccessHelper.PhotoKeys. 194 for(photoAsset of photoAssetList){ 195 let burstKey: string = photoAccessHelper.PhotoKeys.BURST_KEY.toString(); 196 let photoAccessBurstKey: photoAccessHelper.MemberType = photoAsset.get(burstKey).toString(); 197 try { 198 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await 199 phAccessHelper.getBurstAssets(photoAccessBurstKey, fetchOption); 200 if (fetchResult !== undefined) { 201 console.info('fetchResult success'); 202 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 203 if (photoAsset !== undefined) { 204 console.info('photoAsset.displayName :' + photoAsset.displayName); 205 } 206 } 207 } catch (err) { 208 console.error(`getBurstAssets failed, error: ${err.code}, ${err.message}`); 209 } 210 } 211} 212``` 213 214### createAsset 215 216createAsset(photoType: PhotoType, extension: string, options?: photoAccessHelper.CreateOptions): Promise<string> 217 218Creates an image or video asset with the specified file type, file name extension, and options. This API uses a promise to return the result. 219 220If the caller does not have the ohos.permission.WRITE_IMAGEVIDEO permission, you can create a media asset by using a security component. For details, see [Creating a Media Asset Using a Security Component](../../media/medialibrary/photoAccessHelper-savebutton.md). 221 222**Atomic service API**: This API can be used in atomic services since API version 12. 223 224**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 225 226**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 227 228**Parameters** 229 230| Name | Type | Mandatory| Description | 231| --------- | ----------------------------------------------------------- | ---- | ------------------------------------ | 232| photoType | [PhotoType](#phototype) | Yes | Type of the file to create, which can be **IMAGE** or **VIDEO**.| 233| extension | string | Yes | File name extension, for example, **'jpg'**. The value contains 1 to 255 characters. | 234| options | [photoAccessHelper.CreateOptions](arkts-apis-photoAccessHelper-i.md#createoptions) | No | Options for creating the media asset, for example, **{title: 'testPhoto'}**.| 235 236**Return value** 237 238| Type | Description | 239| --------------------- | ---------------------------------------- | 240| Promise<string> | Promise used to return the URI of the created media asset.| 241 242**Error codes** 243 244For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 245 246| ID| Error Message | 247| -------- | ------------------------------------------------------------ | 248| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 249| 201 | Permission denied. | 250| 14000011 | Internal system error. | 251 252**Example** 253 254For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 255 256<!--code_no_check--> 257```ts 258import { photoAccessHelper } from '@kit.MediaLibraryKit'; 259 260async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 261 console.info('createAssetDemo'); 262 try { 263 let photoType: sendablePhotoAccessHelper.PhotoType = sendablePhotoAccessHelper.PhotoType.IMAGE; 264 let extension: string = 'jpg'; 265 let options: photoAccessHelper.CreateOptions = { 266 title: 'testPhoto' 267 } 268 let uri: string = await phAccessHelper.createAsset(photoType, extension, options); 269 console.info('createAsset uri' + uri); 270 console.info('createAsset successfully'); 271 } catch (err) { 272 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 273 } 274} 275``` 276 277### getAlbums 278 279getAlbums(type: AlbumType, subtype: AlbumSubtype, options?: photoAccessHelper.FetchOptions): Promise<FetchResult<Album>> 280 281Obtains albums based on the specified options and album type. This API uses a promise to return the result. 282 283Before the operation, ensure that the albums to obtain exist. 284 285**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 286 287**Required permissions**: ohos.permission.READ_IMAGEVIDEO 288 289**Parameters** 290 291| Name | Type | Mandatory| Description | 292| ------- | --------------------------------------------------------- | ---- | -------------------------------------- | 293| type | [AlbumType](#albumtype) | Yes | Type of the albums to obtain. | 294| subtype | [AlbumSubtype](#albumsubtype) | Yes | Subtype of the album. | 295| options | [photoAccessHelper.FetchOptions](arkts-apis-photoAccessHelper-i.md#fetchoptions) | No | Retrieval options. If this parameter is not specified, the albums are obtained based on the album type by default.| 296 297**Return value** 298 299| Type | Description | 300| ------------------------------------------------------------ | ----------------------------------- | 301| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise used to return the result.| 302 303**Error codes** 304 305For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 306 307| ID| Error Message | 308| -------- | ------------------------------------------------------------ | 309| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 310| 201 | Permission denied. | 311| 14000011 | Internal system error. | 312 313**Example** 314 315For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 316 317<!--code_no_check--> 318```ts 319import { dataSharePredicates } from '@kit.ArkData'; 320import { BusinessError } from '@kit.BasicServicesKit'; 321import { photoAccessHelper } from '@kit.MediaLibraryKit'; 322 323async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 324 // Obtain the album named newAlbumName. 325 console.info('getAlbumsDemo'); 326 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 327 predicates.equalTo('album_name', 'newAlbumName'); 328 let fetchOptions: photoAccessHelper.FetchOptions = { 329 fetchColumns: [], 330 predicates: predicates 331 }; 332 phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions).then( async (fetchResult) => { 333 if (fetchResult === undefined) { 334 console.error('getAlbumsPromise fetchResult is undefined'); 335 return; 336 } 337 let album: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject(); 338 console.info('getAlbumsPromise successfully, albumName: ' + album.albumName); 339 fetchResult.close(); 340 }).catch((err: BusinessError) => { 341 console.error(`getAlbumsPromise failed with err: ${err.code}, ${err.message}`); 342 }); 343} 344``` 345 346### getAlbums 347 348getAlbums(options: photoAccessHelper.FetchOptions): Promise<FetchResult<Album>> 349 350Obtains albums. This API uses a promise to return the result. 351 352Before the operation, ensure that the albums to obtain exist. 353 354**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 355 356**Required permissions**: ohos.permission.READ_IMAGEVIDEO 357 358**Parameters** 359 360| Name | Type | Mandatory| Description | 361| ------- | --------------------------------------------------------- | ---- | -------- | 362| options | [photoAccessHelper.FetchOptions](arkts-apis-photoAccessHelper-i.md#fetchoptions) | Yes | Retrieval options.| 363 364**Return value** 365 366| Type | Description | 367| ------------------------------------------------------------ | ----------------------------------- | 368| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise used to return the result.| 369 370**Error codes** 371 372For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 373 374| ID| Error Message | 375| -------- | ------------------------------------------------------------ | 376| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 377| 201 | Permission denied. | 378| 14000011 | Internal system error. | 379 380**Example** 381 382For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 383 384<!--code_no_check--> 385```ts 386import { dataSharePredicates } from '@kit.ArkData'; 387import { BusinessError } from '@kit.BasicServicesKit'; 388import { photoAccessHelper } from '@kit.MediaLibraryKit'; 389 390async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 391 // Obtain the album named newAlbumName. 392 console.info('getAlbumsDemo'); 393 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 394 predicates.equalTo('album_name', 'newAlbumName'); 395 let fetchOptions: photoAccessHelper.FetchOptions = { 396 fetchColumns: [], 397 predicates: predicates 398 }; 399 phAccessHelper.getAlbums(fetchOptions).then( async (fetchResult) => { 400 if (fetchResult === undefined) { 401 console.error('getAlbumsPromise fetchResult is undefined'); 402 return; 403 } 404 let album: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject(); 405 console.info('getAlbumsPromise successfully, albumName: ' + album.albumName); 406 fetchResult.close(); 407 }).catch((err: BusinessError) => { 408 console.error(`getAlbumsPromise failed with err: ${err.code}, ${err.message}`); 409 }); 410} 411``` 412 413### release 414 415release(): Promise<void> 416 417Releases this PhotoAccessHelper instance. This API uses a promise to return the result. 418Call this API when the APIs of the PhotoAccessHelper instance are no longer used. 419 420**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 421 422**Return value** 423 424| Type | Description | 425| ------------------- | ----------------------- | 426| Promise<void> | Promise that returns no value.| 427 428**Error codes** 429 430For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 431 432| ID| Error Message | 433| -------- | ------------------------------------------------------------ | 434| 14000011 | Internal system error. | 435 436**Example** 437 438For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 439 440<!--code_no_check--> 441```ts 442async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 443 console.info('releaseDemo'); 444 try { 445 console.info('use function...'); 446 } catch (err) { 447 console.error(`function error ...`); 448 }finally{ 449 try{ 450 phAccessHelper?.release(); 451 console.info(`release success`); 452 } catch(e){ 453 console.error(`release error :${e}`); 454 } 455 } 456} 457``` 458 459## PhotoAsset 460 461Provides APIs for encapsulating file asset attributes. 462 463### Properties 464 465**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 466 467| Name | Type | Read-Only| Optional| Description | 468| ----------- | ----------------------- | ---- | ---- | ------------------------------------------------------------ | 469| uri<sup>12+</sup> | string | Yes | No | Media asset URI, for example, **file://media/Photo/1/IMG_datetime_0001/displayName.jpg**. For details, see [Media File URI](../../file-management/user-file-uri-intro.md#media-file-uri).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 470| photoType | [PhotoType](#phototype) | Yes | No | Type of the file. | 471| displayName | string | Yes | No | File name, including the file name extension, to display. The value contains 1 to 255 characters. | 472 473### convertToPhotoAsset 474 475convertToPhotoAsset(): photoAccessHelper.PhotoAsset 476 477Converts a Sendable PhotoAsset object to a non-Sendable PhotoAsset object. 478 479**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 480 481**Return value** 482 483| Type | Description | 484| ---------------------------- | ------------------------------------------------------------ | 485| photoAccessHelper.PhotoAsset | [PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md) of the non-Sendable type.| 486 487**Error codes** 488 489For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 490 491| ID| Error Message | 492| -------- | ------------------------------------------------------------ | 493| 201 | Permission denied. | 494| 14000011 | Internal system error. | 495 496**Example** 497 498For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 499 500<!--code_no_check--> 501```ts 502import { dataSharePredicates } from '@kit.ArkData'; 503import { photoAccessHelper } from '@kit.MediaLibraryKit'; 504 505async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 506 console.info('convertToPhotoAssetDemo'); 507 try { 508 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 509 let fetchOption: photoAccessHelper.FetchOptions = { 510 fetchColumns: ['title'], 511 predicates: predicates 512 }; 513 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 514 let sendablePhotoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 515 let photoAsset: photoAccessHelper.PhotoAsset = sendablePhotoAsset.convertToPhotoAsset(); 516 console.log(`get no sendable uri success : ${photoAsset.uri}`); 517 } catch (err) { 518 console.error(`convertToPhotoAsset failed. error: ${err.code}, ${err.message}`); 519 } 520} 521``` 522 523### get 524 525get(member: string): photoAccessHelper.MemberType 526 527Obtains a **PhotoAsset** member parameter. 528 529**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 530 531**Parameters** 532 533| Name| Type | Mandatory| Description | 534| ------ | ------ | ---- | ------------------------------------------------------------ | 535| member | string | Yes | Name of the member parameter to obtain. <br>Except **'uri'**, **'media_type'**, **'subtype'**, and **'display_name'**, you must pass in [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys) in **fetchColumns**. For example, to obtain the title, pass in **fetchColumns: ['title']**.| 536 537**Return value** 538 539| Type | Description | 540| ----------------------------------------------------- | ---------------------------- | 541| [photoAccessHelper.MemberType](arkts-apis-photoAccessHelper-t.md#membertype) | **PhotoAsset** member parameter obtained.| 542 543**Error codes** 544 545For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 546 547| ID| Error Message | 548| -------- | ------------------------------------------------------------ | 549| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 550 551**Example** 552 553For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 554 555<!--code_no_check--> 556```ts 557import { dataSharePredicates } from '@kit.ArkData'; 558import { photoAccessHelper } from '@kit.MediaLibraryKit'; 559 560async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 561 console.info('photoAssetGetDemo'); 562 try { 563 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 564 let fetchOption: photoAccessHelper.FetchOptions = { 565 fetchColumns: ['title'], 566 predicates: predicates 567 }; 568 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 569 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 570 let title: photoAccessHelper.PhotoKeys = photoAccessHelper.PhotoKeys.TITLE; 571 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title.toString()); 572 console.info('photoAsset Get photoAssetTitle = ', photoAssetTitle); 573 } catch (err) { 574 console.error(`get failed. error: ${err.code}, ${err.message}`); 575 } 576} 577``` 578 579### set 580 581set(member: string, value: string): void 582 583Sets a **PhotoAsset** member parameter. 584 585**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 586 587**Parameters** 588 589| Name| Type | Mandatory| Description | 590| ------ | ------ | ---- | ------------------------------------------------------------ | 591| member | string | Yes | Name of the parameter to set, for example, [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys).TITLE. The value contains 1 to 255 characters.| 592| value | string | Yes | Value to set. Only the value of [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys).TITLE can be changed. The title must meet the following requirements:<br>- It does not contain a file name extension.<br>- The file name, which is in the format of title+file name extension, does not exceed 255 characters.<br>- The title does not contain any of the following characters:\ / : * ? " ' ` < > \| { } [ ] | 593 594**Error codes** 595 596For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 597 598| ID| Error Message | 599| -------- | ------------------------------------------------------------ | 600| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 601 602**Example** 603 604For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 605 606<!--code_no_check--> 607```ts 608import { dataSharePredicates } from '@kit.ArkData'; 609import { photoAccessHelper } from '@kit.MediaLibraryKit'; 610 611async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 612 console.info('photoAssetSetDemo'); 613 try { 614 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 615 let fetchOption: photoAccessHelper.FetchOptions = { 616 fetchColumns: ['title'], 617 predicates: predicates 618 }; 619 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 620 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 621 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 622 photoAsset.set(title, 'newTitle'); 623 } catch (err) { 624 console.error(`set failed. error: ${err.code}, ${err.message}`); 625 } 626} 627``` 628 629### commitModify 630 631commitModify(): Promise<void> 632 633Commits the modification on the file metadata to the database. This API uses a promise to return the result. 634 635**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 636 637**Atomic service API**: This API can be used in atomic services since API version 12. 638 639**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 640 641**Return value** 642 643| Type | Description | 644| ------------------- | ----------------------- | 645| Promise<void> | Promise that returns no value.| 646 647**Error codes** 648 649For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 650 651| ID| Error Message | 652| -------- | ------------------------------------------------------------ | 653| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 654| 201 | Permission denied. | 655| 14000011 | Internal system error. | 656 657**Example** 658 659For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 660 661<!--code_no_check--> 662```ts 663import { dataSharePredicates } from '@kit.ArkData'; 664import { photoAccessHelper } from '@kit.MediaLibraryKit'; 665 666async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 667 console.info('commitModifyDemo'); 668 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 669 let fetchOption: photoAccessHelper.FetchOptions = { 670 fetchColumns: ['title'], 671 predicates: predicates 672 }; 673 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 674 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 675 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 676 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 677 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 678 photoAsset.set(title, 'newTitle3'); 679 try { 680 await photoAsset.commitModify(); 681 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 682 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 683 } catch (err) { 684 console.error(`commitModify failed. error: ${err.code}, ${err.message}`); 685 } 686} 687``` 688 689### getThumbnail 690 691getThumbnail(size?: image.Size): Promise<image.PixelMap> 692 693Obtains the file thumbnail of the given size. This API uses a promise to return the result. 694 695**Required permissions**: ohos.permission.READ_IMAGEVIDEO 696 697**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 698 699**Parameters** 700 701| Name| Type | Mandatory| Description | 702| ------ | ----------------------------------------------------- | ---- | ------------ | 703| size | [image.Size](../apis-image-kit/arkts-apis-image-i.md#size) | No | Size of the thumbnail.| 704 705**Return value** 706 707| Type | Description | 708| ------------------------------------------------------------ | ----------------------------------- | 709| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return the PixelMap of the thumbnail.| 710 711**Error codes** 712 713For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 714 715| ID| Error Message | 716| -------- | ------------------------------------------------------------ | 717| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 718| 201 | Permission denied. | 719| 14000011 | Internal system error. | 720 721**Example** 722 723For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 724 725<!--code_no_check--> 726```ts 727import { dataSharePredicates } from '@kit.ArkData'; 728import { image } from '@kit.ImageKit'; 729import { BusinessError } from '@kit.BasicServicesKit'; 730import { photoAccessHelper } from '@kit.MediaLibraryKit'; 731 732async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 733 console.info('getThumbnailDemo'); 734 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 735 let fetchOption: photoAccessHelper.FetchOptions = { 736 fetchColumns: [], 737 predicates: predicates 738 }; 739 let size: image.Size = { width: 720, height: 720 }; 740 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 741 let asset = await fetchResult.getFirstObject(); 742 console.info('asset displayName = ', asset.displayName); 743 asset.getThumbnail(size).then((pixelMap) => { 744 console.info('getThumbnail successful ' + pixelMap); 745 }).catch((err: BusinessError) => { 746 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 747 }); 748} 749``` 750 751## FetchResult 752 753Provides APIs to manage the file retrieval result. 754 755### getCount 756 757getCount(): number 758 759Obtains the total number of files in the result set. 760 761**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 762 763**Return value** 764 765| Type | Description | 766| ------ | ------------------ | 767| number | Total number of files obtained.| 768 769**Error codes** 770 771For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 772 773| ID| Error Message | 774| -------- | ------------------------------------------------------------ | 775| 14000011 | Internal system error. | 776 777**Example** 778 779For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 780 781<!--code_no_check--> 782```ts 783import { dataSharePredicates } from '@kit.ArkData'; 784import { photoAccessHelper } from '@kit.MediaLibraryKit'; 785 786async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 787 console.info('getCountDemo'); 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('fetchCount = ', fetchCount); 796} 797``` 798 799### isAfterLast 800 801isAfterLast(): boolean 802 803Checks whether the cursor is in the last row of the result set. 804 805**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 806 807**Return value** 808 809| Type | Description | 810| ------- | ----------------------------------------------------------- | 811| boolean | Returns **true** if the cursor is in the last row of the result set; returns **false** otherwise.| 812 813**Error codes** 814 815For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 816 817| ID| Error Message | 818| -------- | ------------------------------------------------------------ | 819| 14000011 | Internal system error. | 820 821**Example** 822 823For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 824 825<!--code_no_check--> 826```ts 827import { dataSharePredicates } from '@kit.ArkData'; 828import { photoAccessHelper } from '@kit.MediaLibraryKit'; 829 830async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 831 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 832 let fetchOption: photoAccessHelper.FetchOptions = { 833 fetchColumns: [], 834 predicates: predicates 835 }; 836 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 837 let fetchCount = fetchResult.getCount(); 838 console.info('count:' + fetchCount); 839 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getLastObject(); 840 if (fetchResult.isAfterLast()) { 841 console.info('photoAsset isAfterLast displayName = ', photoAsset.displayName); 842 } else { 843 console.info('photoAsset not isAfterLast.'); 844 } 845} 846``` 847 848### close 849 850close(): void 851 852Closes this FetchResult instance to invalidate it. After this instance is closed, the APIs in this instance cannot be invoked. 853 854**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 855 856**Error codes** 857 858For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 859 860| ID| Error Message | 861| -------- | ------------------------------------------------------------ | 862| 14000011 | Internal system error. | 863 864**Example** 865 866For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 867 868<!--code_no_check--> 869```ts 870import { dataSharePredicates } from '@kit.ArkData'; 871import { photoAccessHelper } from '@kit.MediaLibraryKit'; 872 873async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 874 console.info('fetchResultCloseDemo'); 875 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 876 let fetchOption: photoAccessHelper.FetchOptions = { 877 fetchColumns: [], 878 predicates: predicates 879 }; 880 try { 881 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 882 fetchResult.close(); 883 console.info('close succeed.'); 884 } catch (err) { 885 console.error(`close fail. error: ${err.code}, ${err.message}`); 886 } 887} 888``` 889 890### getFirstObject 891 892getFirstObject(): Promise<T> 893 894Obtains the first asset in the result set. This API uses a promise to return the result. 895 896**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 897 898**Return value** 899 900| Type | Description | 901| ---------------- | ------------------------------------- | 902| Promise<T> | Promise used to return the first object in the result set.| 903 904**Error codes** 905 906For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 907 908| ID| Error Message | 909| -------- | ------------------------------------------------------------ | 910| 14000011 | Internal system error. | 911 912**Example** 913 914For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 915 916<!--code_no_check--> 917```ts 918import { dataSharePredicates } from '@kit.ArkData'; 919import { photoAccessHelper } from '@kit.MediaLibraryKit'; 920 921async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 922 console.info('getFirstObjectDemo'); 923 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 924 let fetchOption: photoAccessHelper.FetchOptions = { 925 fetchColumns: [], 926 predicates: predicates 927 }; 928 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 929 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 930 console.info('photoAsset displayName: ', photoAsset.displayName); 931} 932``` 933 934### getNextObject 935 936getNextObject(): Promise<T> 937 938Obtains the next asset in the result set. This API uses a promise to return the result. 939Before using this API, you must use [isAfterLast()](#isafterlast) to check whether the current position is the end of the result set. 940 941**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 942 943**Return value** 944 945| Type | Description | 946| ---------------- | ------------------------------------- | 947| Promise<T> | Promise used to return the next object in the result set.| 948 949**Error codes** 950 951For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 952 953| ID| Error Message | 954| -------- | ------------------------------------------------------------ | 955| 14000011 | Internal system error. | 956 957**Example** 958 959For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 960 961<!--code_no_check--> 962```ts 963import { dataSharePredicates } from '@kit.ArkData'; 964import { photoAccessHelper } from '@kit.MediaLibraryKit'; 965 966async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 967 console.info('getNextObjectDemo'); 968 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 969 let fetchOption: photoAccessHelper.FetchOptions = { 970 fetchColumns: [], 971 predicates: predicates 972 }; 973 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 974 await fetchResult.getFirstObject(); 975 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getNextObject(); 976 console.info('photoAsset displayName: ', photoAsset.displayName); 977} 978``` 979 980### getLastObject 981 982getLastObject(): Promise<T> 983 984Obtains the last asset in the result set. This API uses a promise to return the result. 985 986**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 987 988**Return value** 989 990| Type | Description | 991| ---------------- | --------------------------------------- | 992| Promise<T> | Promise used to return the last object in the result set.| 993 994**Error codes** 995 996For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 997 998| ID| Error Message | 999| -------- | ------------------------------------------------------------ | 1000| 14000011 | Internal system error. | 1001 1002**Example** 1003 1004For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 1005 1006<!--code_no_check--> 1007```ts 1008import { dataSharePredicates } from '@kit.ArkData'; 1009import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1010 1011async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 1012 console.info('getLastObjectDemo'); 1013 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1014 let fetchOption: photoAccessHelper.FetchOptions = { 1015 fetchColumns: [], 1016 predicates: predicates 1017 }; 1018 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1019 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getLastObject(); 1020 console.info('photoAsset displayName: ', photoAsset.displayName); 1021} 1022``` 1023 1024### getObjectByPosition 1025 1026getObjectByPosition(index: number): Promise<T> 1027 1028Obtains the asset with the given index in the result set. This API uses a promise to return the result. 1029 1030**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1031 1032**Parameters** 1033 1034| Name| Type | Mandatory| Description | 1035| ------ | ------ | ---- | ----------------------------- | 1036| index | number | Yes | Index of the asset to obtain. The value starts from **0**.| 1037 1038**Return value** 1039 1040| Type | Description | 1041| ---------------- | --------------------------------------------- | 1042| Promise<T> | Promise used to return the asset obtained.| 1043 1044**Error codes** 1045 1046For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 1047 1048| ID| Error Message | 1049| -------- | ------------------------------------------------------------ | 1050| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1051| 14000011 | Internal system error. | 1052 1053**Example** 1054 1055For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 1056 1057<!--code_no_check--> 1058```ts 1059import { dataSharePredicates } from '@kit.ArkData'; 1060import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1061 1062async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 1063 console.info('getObjectByPositionDemo'); 1064 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1065 let fetchOption: photoAccessHelper.FetchOptions = { 1066 fetchColumns: [], 1067 predicates: predicates 1068 }; 1069 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1070 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getObjectByPosition(0); 1071 console.info('photoAsset displayName: ', photoAsset.displayName); 1072} 1073``` 1074 1075### getAllObjects 1076 1077getAllObjects(): Promise<Array<T>> 1078 1079Obtains all the file assets in the result set. This API uses a promise to return the result. 1080 1081**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1082 1083**Return value** 1084 1085| Type | Description | 1086| ----------------------------- | ------------------------------------------- | 1087| Promise<Array<T>> | Promise used to return all the assets in the result set.| 1088 1089**Error codes** 1090 1091For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 1092 1093| ID| Error Message | 1094| -------- | ------------------------------------------------------------ | 1095| 14000011 | Internal system error. | 1096 1097**Example** 1098 1099For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 1100 1101<!--code_no_check--> 1102```ts 1103import { dataSharePredicates } from '@kit.ArkData'; 1104import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1105 1106async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 1107 console.info('getAllObjectDemo'); 1108 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1109 let fetchOption: photoAccessHelper.FetchOptions = { 1110 fetchColumns: [], 1111 predicates: predicates 1112 }; 1113 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1114 let photoAssetList: Array<sendablePhotoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects(); 1115 console.info('photoAssetList length: ', photoAssetList.length); 1116} 1117``` 1118 1119## Album 1120 1121Provides APIs to manage albums. 1122 1123### Properties 1124 1125**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1126 1127| Name | Type | Read-Only | Optional| Description | 1128| ------------ | ----------------------------- | ---------------------------- | ---- | ---------------- | 1129| albumType | [AlbumType](#albumtype) | Yes | No | Type of the album. | 1130| albumSubtype | [AlbumSubtype](#albumsubtype) | Yes | No | Subtype of the album. | 1131| albumName | string | Yes for a user album; no for a system album.| No | Name of the album. | 1132| albumUri | string | Yes | No | URI of the album. | 1133| count | number | Yes | No | Number of files in the album.| 1134| coverUri | string | Yes | No | URI of the cover file of the album. | 1135| imageCount | number | Yes | Yes | Number of images in the album.| 1136| videoCount | number | Yes | Yes | Number of videos in the album.| 1137 1138### convertToPhotoAlbum 1139 1140convertToPhotoAlbum(): photoAccessHelper.Album 1141 1142Converts this Sendable album to a non-Sendable album. 1143 1144**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1145 1146**Return value** 1147 1148| Type | Description | 1149| ---------------------------- | ------------------------------------------------------------ | 1150| [photoAccessHelper.Album](arkts-apis-photoAccessHelper-Album.md) | Album of the non-Sendable type.| 1151 1152**Error codes** 1153 1154For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 1155 1156| ID| Error Message | 1157| -------- | ------------------------------------------------------------ | 1158| 201 | Permission denied. | 1159| 14000011 | Internal system error. | 1160 1161**Example** 1162 1163For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 1164 1165<!--code_no_check--> 1166```ts 1167import { dataSharePredicates } from '@kit.ArkData'; 1168import { BusinessError } from '@kit.BasicServicesKit'; 1169import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1170 1171async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 1172 console.info('convertToPhotoAlbumDemo'); 1173 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1174 let albumFetchOptions: photoAccessHelper.FetchOptions = { 1175 fetchColumns: [], 1176 predicates: predicates 1177 }; 1178 let fetchOption: photoAccessHelper.FetchOptions = { 1179 fetchColumns: [], 1180 predicates: predicates 1181 }; 1182 let albumList: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.Album> = await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 1183 let sendableAlbum: sendablePhotoAccessHelper.Album = await albumList.getFirstObject(); 1184 let album: photoAccessHelper.Album = sendableAlbum.convertToPhotoAlbum(); 1185 album.getAssets(fetchOption).then((albumFetchResult) => { 1186 console.info('convertToPhotoAlbum successfully, getCount: ' + albumFetchResult.getCount()); 1187 }).catch((err: BusinessError) => { 1188 console.error(`convertToPhotoAlbum failed with error: ${err.code}, ${err.message}`); 1189 }); 1190} 1191``` 1192 1193### getAssets 1194 1195getAssets(options: FetchOptions): Promise<FetchResult<PhotoAsset>> 1196 1197Obtains media assets. This API uses a promise to return the result. 1198 1199**Required permissions**: ohos.permission.READ_IMAGEVIDEO 1200 1201**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1202 1203**Parameters** 1204 1205| Name | Type | Mandatory| Description | 1206| ------- | --------------------------------------------------------- | ---- | ---------- | 1207| options | [FetchOptions](arkts-apis-photoAccessHelper-i.md#fetchoptions) | Yes | Retrieval options.| 1208 1209**Return value** 1210 1211| Type | Description | 1212| ------------------------------------------------------------ | --------------------------------------- | 1213| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise used to return the media assets obtained.| 1214 1215**Error codes** 1216 1217For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 1218 1219| ID| Error Message | 1220| -------- | ------------------------------------------------------------ | 1221| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1222| 201 | Permission denied. | 1223| 13900020 | Invalid argument. | 1224| 14000011 | Internal system error. | 1225 1226**Example** 1227 1228For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 1229 1230<!--code_no_check--> 1231```ts 1232import { dataSharePredicates } from '@kit.ArkData'; 1233import { BusinessError } from '@kit.BasicServicesKit'; 1234import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1235 1236async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 1237 console.info('albumGetAssetsDemoPromise'); 1238 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1239 let albumFetchOptions: photoAccessHelper.FetchOptions = { 1240 fetchColumns: [], 1241 predicates: predicates 1242 }; 1243 let fetchOption: photoAccessHelper.FetchOptions = { 1244 fetchColumns: [], 1245 predicates: predicates 1246 }; 1247 let albumList: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.Album> = await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 1248 let album: sendablePhotoAccessHelper.Album = await albumList.getFirstObject(); 1249 album.getAssets(fetchOption).then((albumFetchResult) => { 1250 console.info('album getAssets successfully, getCount: ' + albumFetchResult.getCount()); 1251 }).catch((err: BusinessError) => { 1252 console.error(`album getAssets failed with error: ${err.code}, ${err.message}`); 1253 }); 1254} 1255``` 1256 1257### commitModify 1258 1259commitModify(): Promise<void> 1260 1261Commits the modification on the album attributes to the database. This API uses a promise to return the result. 1262 1263**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 1264 1265**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1266 1267**Return value** 1268 1269| Type | Description | 1270| ------------------- | ----------------------- | 1271| Promise<void> | Promise that returns no value.| 1272 1273**Error codes** 1274 1275For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 1276 1277| ID| Error Message | 1278| -------- | ------------------------------------------------------------ | 1279| 201 | Permission denied. | 1280| 14000011 | Internal system error. | 1281 1282**Example** 1283 1284For details about how to create a phAccessHelper instance, see the example provided in [sendablePhotoAccessHelper.getPhotoAccessHelper](#sendablephotoaccesshelpergetphotoaccesshelper). 1285 1286<!--code_no_check--> 1287```ts 1288import { dataSharePredicates } from '@kit.ArkData'; 1289import { BusinessError } from '@kit.BasicServicesKit'; 1290import { photoAccessHelper } from '@kit.MediaLibraryKit'; 1291 1292async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 1293 console.info('albumCommitModifyDemo'); 1294 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1295 let albumFetchOptions: photoAccessHelper.FetchOptions = { 1296 fetchColumns: [], 1297 predicates: predicates 1298 }; 1299 let albumList: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.Album> = await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.USER, sendablePhotoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 1300 let album: sendablePhotoAccessHelper.Album = await albumList.getFirstObject(); 1301 album.albumName = 'hello'; 1302 album.commitModify().then(() => { 1303 console.info('commitModify successfully'); 1304 }).catch((err: BusinessError) => { 1305 console.error(`commitModify failed with error: ${err.code}, ${err.message}`); 1306 }); 1307} 1308``` 1309 1310## PhotoType 1311 1312Enumerates media file types. 1313 1314**Atomic service API**: This API can be used in atomic services since API version 12. 1315 1316**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1317 1318| Name | Value | Description | 1319| ----- | ---- | ------ | 1320| IMAGE | 1 | Image.| 1321| VIDEO | 2 | Video.| 1322 1323## PhotoSubtype<sup>14+</sup> 1324 1325Enumerates the [PhotoAsset](#photoasset) types. 1326 1327**Atomic service API**: This API can be used in atomic services since API version 14. 1328 1329**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1330 1331| Name | Value| Description| 1332| ----- | ---- | ---- | 1333| DEFAULT | 0 | Photo, which is the default type.| 1334| MOVING_PHOTO | 3 | Moving photo.| 1335| BURST | 4 | Burst photo.| 1336 1337## DynamicRangeType<sup>14+</sup> 1338 1339Enumerates the dynamic range types of media assets. 1340 1341**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1342 1343| Name | Value| Description| 1344| ----- | ---- | ---- | 1345| SDR | 0 | Standard dynamic range (SDR).| 1346| HDR | 1 | High dynamic range (HDR). | 1347 1348## AlbumType 1349 1350Enumerates the album types. 1351 1352**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1353 1354| Name | Value | Description | 1355| ------ | ---- | -------------- | 1356| USER | 0 | User album. | 1357| SYSTEM | 1024 | System album.| 1358 1359## AlbumSubtype 1360 1361Enumerate the album subtypes. 1362 1363**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 1364 1365| Name | Value | Description | 1366| ------------- | ---------- | ---------- | 1367| USER\_GENERIC | 1 | User album.| 1368| FAVORITE | 1025 | Favorites. | 1369| VIDEO | 1026 | Video album.| 1370| IMAGE | 1031 | Photo album.| 1371| ANY | 2147483647 | Any album.| 1372
