1# MediaLibrary 2 3> **NOTE** 4> 5> This component is supported since API version 6. Updates will be marked with a superscript to indicate their earliest API version. 6 7## Modules to Import 8``` 9import mediaLibrary from '@ohos.multimedia.mediaLibrary'; 10``` 11 12## mediaLibrary.getMediaLibrary<sup>8+</sup> 13 14getMediaLibrary(context: Context): MediaLibrary 15 16Obtains a **MediaLibrary** instance, which is used to access and modify personal media data such as audios, videos, images, and documents. 17 18This API can be used only in the stage model. 19 20**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 21 22**Parameters** 23 24| Name | Type | Mandatory| Description | 25| ------- | ------- | ---- | -------------------------- | 26| context | Context | Yes | Context of the ability.| 27 28**Return value** 29 30| Type | Description | 31| ----------------------------- | :---- | 32| [MediaLibrary](#medialibrary) | **MediaLibrary** instance.| 33 34**Example (from API version 9)** 35 36``` 37var media = mediaLibrary.getMediaLibrary(this.context); 38``` 39 40**Example (API version 8)** 41 42``` 43import featureAbility from '@ohos.ability.featureAbility'; 44 45var context = featureAbility.getContext() 46var media = mediaLibrary.getMediaLibrary(context); 47``` 48## mediaLibrary.getMediaLibrary 49 50getMediaLibrary(): MediaLibrary 51 52Obtains a **MediaLibrary** instance, which is used to access and modify personal media data such as audios, videos, images, and documents. 53 54This API can be used only in the FA model. 55 56> **NOTE** 57> 58> This API is no longer maintained since API version 8. You are advised to use [mediaLibrary.getMediaLibrary<sup>8+</sup>](#medialibrarygetmedialibrary8) instead. 59 60**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 61 62**Return value** 63 64| Type | Description | 65| ----------------------------- | :--------- | 66| [MediaLibrary](#medialibrary) | **MediaLibrary** instance.| 67 68**Example** 69 70```js 71var media = mediaLibrary.getMediaLibrary(); 72``` 73 74## MediaLibrary 75 76### getFileAssets<sup>7+</sup> 77 78 79getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void 80 81Obtains file assets (also called files). This API uses an asynchronous callback to return the result. 82 83**Required permissions**: ohos.permission.READ_MEDIA 84 85**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 86 87**Parameters** 88 89| Name | Type | Mandatory| Description | 90| -------- | --------------------------------------------------- | ---- | --------------------------------- | 91| options | [MediaFetchOptions](#mediafetchoptions7) | Yes | Options for fetching the files. | 92| callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | Yes | Asynchronous callback of **FetchFileResult**.| 93 94**Example** 95 96``` 97let fileKeyObj = mediaLibrary.FileKey 98let imageType = mediaLibrary.MediaType.IMAGE 99let imagesfetchOp = { 100 selections: fileKeyObj.MEDIA_TYPE + '= ?', 101 selectionArgs: [imageType.toString()], 102}; 103media.getFileAssets(imagesfetchOp, (error, fetchFileResult) => { 104 if (fetchFileResult != undefined) { 105 console.info('mediaLibraryTest : ASSET_CALLBACK fetchFileResult success'); 106 fetchFileResult.getAllObject((err, fileAssetList) => { 107 if (fileAssetList != undefined) { 108 fileAssetList.forEach(function(getAllObjectInfo){ 109 console.info("getAllObjectInfo.displayName :" + getAllObjectInfo.displayName); 110 }); 111 } 112 }); 113 } 114}); 115``` 116### getFileAssets<sup>7+</sup> 117 118getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> 119 120Obtains file assets. This API uses a promise to return the result. 121 122**Required permissions**: ohos.permission.READ_MEDIA 123 124**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 125 126**Parameters** 127 128| Name | Type | Mandatory| Description | 129| ------- | ---------------------------------------- | ---- | ------------ | 130| options | [MediaFetchOptions](#mediafetchoptions7) | Yes | Options for fetching the files.| 131 132**Return value** 133 134| Type | Description | 135| ------------------------------------ | -------------- | 136| [FetchFileResult](#fetchfileresult7) | Result set of the file retrieval operation.| 137 138**Example** 139 140``` 141let fileKeyObj = mediaLibrary.FileKey 142let imageType = mediaLibrary.MediaType.IMAGE 143let imagesfetchOp = { 144 selections: fileKeyObj.MEDIA_TYPE + '= ?', 145 selectionArgs: [imageType.toString()], 146}; 147media.getFileAssets(imagesfetchOp).then(function(fetchFileResult){ 148 console.info("getFileAssets successfully: image number is "+ fetchFileResult.getCount()); 149}).catch(function(err){ 150 console.info("getFileAssets failed with error:"+ err); 151}); 152``` 153 154### on<sup>8+</sup> 155 156on(type: 'deviceChange'|'albumChange'|'imageChange'|'audioChange'|'videoChange'|'fileChange'|'remoteFileChange', callback: Callback<void>): void 157 158Subscribes to the media library changes. This API uses an asynchronous callback to return the result. 159 160**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 161 162**Parameters** 163 164| Name | Type | Mandatory | Description | 165| -------- | -------------------- | ---- | ---------------------------------------- | 166| type | string | Yes | Media type.<br>'deviceChange': registered device change<br>'albumChange': album change<br>'imageChange': image file change<br>'audioChange': audio file change<br>'videoChange': video file change<br>'fileChange': file change<br>'remoteFileChange': file change on the registered device| 167| callback | callback<void> | Yes | Void callback. | 168 169**Example** 170 171``` 172media.on('imageChange', () => { 173 // image file had changed, do something 174}) 175``` 176### off<sup>8+</sup> 177 178off(type: 'deviceChange'|'albumChange'|'imageChange'|'audioChange'|'videoChange'|'fileChange'|'remoteFileChange', callback?: Callback<void>): void 179 180Unsubscribes from the media library changes. This API uses an asynchronous callback to return the result. 181 182**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 183 184**Parameters** 185 186| Name | Type | Mandatory | Description | 187| -------- | -------------------- | ---- | ---------------------------------------- | 188| type | string | Yes | Media type.<br>'deviceChange': registered device change<br>'albumChange': album change<br>'imageChange': image file change<br>'audioChange': audio file change<br>'videoChange': video file change<br>'fileChange': file change<br>'remoteFileChange': file change on the registered device| 189| callback | callback<void> | No | Void callback. | 190 191**Example** 192 193``` 194media.off('imageChange', () => { 195 // stop listening success 196}) 197``` 198 199### createAsset <sup>8+</sup> 200 201createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void 202 203Creates a media asset. This API uses an asynchronous callback to return the result. 204 205**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 206 207**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 208 209**Parameters** 210 211| Name | Type | Mandatory| Description | 212| ------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 213| mediaType | [MediaType](#mediatype8) | Yes | Media type. | 214| displayName | string | Yes | Display file name. | 215| relativePath | string | Yes | Path for storing the file. You can use [getPublicDirectory](#getpublicdirectory8) to obtain the paths for storing different types of files.| 216| callback | AsyncCallback<[FileAsset](#fileasset7)> | Yes | Asynchronous callback for **FileAsset**. | 217 218**Example** 219 220``` 221async function example() { 222 // Create an image file in callback mode. 223 let mediaType = mediaLibrary.MediaType.IMAGE; 224 let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; 225 const path = await media.getPublicDirectory(DIR_IMAGE); 226 media.createAsset(mediaType, 'imageCallBack.jpg', path + 'myPicture/', (err, fileAsset) => { 227 if (fileAsset != undefined) { 228 console.info('createAsset successfully, message = ' + err); 229 } else { 230 console.info('createAsset failed, message = ' + err); 231 } 232 }); 233} 234``` 235 236### createAsset<sup>8+</sup> 237 238createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset> 239 240Creates a media asset. This API uses a promise to return the result. 241 242**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 243 244**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 245 246**Parameters** 247 248| Name | Type | Mandatory| Description | 249| ------------ | ------------------------ | ---- | ------------------------------------------------------------ | 250| mediaType | [MediaType](#mediatype8) | Yes | Media type. | 251| displayName | string | Yes | Display file name. | 252| relativePath | string | Yes | Relative path. You can use [getPublicDirectory](#getpublicdirectory8) to obtain the relative path of the level-1 directory of different types of media files.| 253 254**Return value** 255 256| Type | Description | 257| ------------------------ | ----------------- | 258| [FileAsset](#fileasset7) | Media data (FileAsset).| 259 260**Example** 261 262``` 263let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; 264media.getPublicDirectory(DIR_CAMERA).then(function(dicResult){ 265 console.info("getPublicDirectory successfully:"+ JSON.stringify(dicResult)); 266}).catch(function(err){ 267 console.info("getPublicDirectory failed with error:"+ err); 268}); 269``` 270 271### getPublicDirectory<sup>8+</sup> 272 273getPublicDirectory(type: DirectoryType, callback: AsyncCallback<string>): void 274 275Obtains a public directory. This API uses an asynchronous callback to return the result. 276 277**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 278 279**Parameters** 280 281| Name | Type | Mandatory| Description | 282| -------- | -------------------------------- | ---- | ------------------------- | 283| type | [DirectoryType](#directorytype8) | Yes | Type of the public directory. | 284| callback | AsyncCallback<string> | Yes | Callback used to return the public directory.| 285 286**Example** 287 288``` 289let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; 290media.getPublicDirectory(DIR_CAMERA, (err, dicResult) => { 291 if (dicResult == 'Camera/') { 292 console.info('mediaLibraryTest : getPublicDirectory passed'); 293 } else { 294 console.info('mediaLibraryTest : getPublicDirectory failed'); 295 } 296}); 297``` 298 299### getPublicDirectory<sup>8+</sup> 300 301getPublicDirectory(type: DirectoryType): Promise<string> 302 303Obtains a public directory. This API uses a promise to return the result. 304 305**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 306 307**Parameters** 308 309| Name| Type | Mandatory| Description | 310| ------ | -------------------------------- | ---- | ------------ | 311| type | [DirectoryType](#directorytype8) | Yes | Type of the public directory.| 312 313**Return value** 314 315| Type | Description | 316| ---------------- | ---------------- | 317| Promise\<string> | Promise used to return the public directory.| 318 319**Example** 320 321``` 322async function example() { 323 let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; 324 const dicResult = await media.getPublicDirectory(DIR_CAMERA); 325 if (dicResult == 'Camera/') { 326 console.info('MediaLibraryTest : getPublicDirectory'); 327 } else { 328 console.info('MediaLibraryTest : getPublicDirectory failed'); 329 } 330} 331``` 332 333### getAlbums<sup>7+</sup> 334 335getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album>>): void 336 337Obtains the albums. This API uses an asynchronous callback to return the result. 338 339**Required permissions**: ohos.permission.READ_MEDIA 340 341**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 342 343**Parameters** 344 345| Name | Type | Mandatory| Description | 346| -------- | -------------------------------------------- | ---- | --------------------------- | 347| options | [MediaFetchOptions](#mediafetchoptions7) | Yes | Options for fetching the albums. | 348| callback | AsyncCallback<Array<[Album](#album7)>> | Yes | Callback used to return the albums.| 349 350**Example** 351 352``` 353let AlbumNoArgsfetchOp = { 354 selections: '', 355 selectionArgs: [], 356}; 357media.getAlbums(AlbumNoArgsfetchOp, (err, albumList) => { 358 if (albumList != undefined) { 359 const album = albumList[0]; 360 console.info('album.albumName = ' + album.albumName); 361 console.info('album.count = ' + album.count); 362 } else { 363 console.info('getAlbum fail, message = ' + err); 364 } 365}) 366``` 367 368### getAlbums<sup>7+</sup> 369 370getAlbums(options: MediaFetchOptions): Promise<Array<Album>> 371 372Obtains the albums. This API uses a promise to return the result. 373 374**Required permissions**: ohos.permission.READ_MEDIA 375 376**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 377 378**Parameters** 379 380| Name | Type | Mandatory| Description | 381| ------- | ---------------------------------------- | ---- | ------------ | 382| options | [MediaFetchOptions](#mediafetchoptions7) | Yes | Options for fetching the albums.| 383 384**Return value** 385 386| Type | Description | 387| -------------------------------- | ------------- | 388| Promise<Array<[Album](#album7)>> | Promise used to return the albums.| 389 390**Example** 391 392``` 393let AlbumNoArgsfetchOp = { 394 selections: '', 395 selectionArgs: [], 396}; 397media.getAlbums(AlbumNoArgsfetchOp).then(function(albumList){ 398 console.info("getAlbums successfully:"+ JSON.stringify(albumList)); 399}).catch(function(err){ 400 console.info("getAlbums failed with error:"+ err); 401}); 402``` 403 404### release<sup>8+</sup> 405 406release(callback: AsyncCallback<void>): void 407 408Releases this **MediaLibrary** instance. 409Call this API when you no longer need to use the APIs in the **MediaLibrary** instance. 410 411**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 412 413**Parameters** 414 415| Name | Type | Mandatory | Description | 416| -------- | ------------------------- | ---- | ---------- | 417| callback | AsyncCallback<void> | Yes | Callback used to return the execution result.| 418 419**Example** 420 421``` 422var media = mediaLibrary.getMediaLibrary(context); 423media.release((err) => { 424 // do something 425}); 426``` 427 428### release<sup>8+</sup> 429 430release(): Promise<void> 431 432Releases this **MediaLibrary** instance. 433Call this API when you no longer need to use the APIs in the **MediaLibrary** instance. 434 435**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 436 437**Return value** 438 439| Type | Description | 440| ------------------- | -------------------- | 441| Promise<void> | Promise used to return the execution result.| 442 443**Example** 444 445``` 446media.release() 447``` 448 449### storeMediaAsset<sup>(deprecated)</sup> 450 451storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback<string>): void 452 453Stores a media asset. This API uses an asynchronous callback to return the URI that stores the media asset. 454 455> **NOTE** 456> 457> This API is deprecated since API version 9. 458 459**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 460 461**Parameters** 462 463| Name | Type | Mandatory | Description | 464| -------- | ------------------------------------- | ---- | ----------------------- | 465| option | [MediaAssetOption](#mediaassetoption) | Yes | Media asset option. | 466| callback | AsyncCallback<string> | Yes | Callback used to return the URI that stores the media asset.| 467 468**Example** 469 470 ``` 471let option = { 472 src : "/data/storage/el2/base/haps/entry/image.png", 473 mimeType : "image/*", 474 relativePath : "Pictures/" 475}; 476mediaLibrary.getMediaLibrary().storeMediaAsset(option, (err, value) => { 477 if (err) { 478 console.log("An error occurred when storing the media asset."); 479 return; 480 } 481 console.log("Media asset stored."); 482 // Obtain the URI that stores the media asset. 483}); 484 ``` 485 486 487### storeMediaAsset<sup>(deprecated)</sup> 488 489storeMediaAsset(option: MediaAssetOption): Promise<string> 490 491Stores a media asset. This API uses a promise to return the URI that stores the media asset. 492 493> **NOTE** 494> 495> This API is deprecated since API version 9. 496 497**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 498 499**Parameters** 500 501| Name | Type | Mandatory | Description | 502| ------ | ------------------------------------- | ---- | ------- | 503| option | [MediaAssetOption](#mediaassetoption) | Yes | Media asset option.| 504 505**Return value** 506 507| Type | Description | 508| --------------------- | ---------------------------- | 509| Promise<string> | Promise used to return the URI that stores the media asset.| 510 511**Example** 512 513 ``` 514let option = { 515 src : "/data/storage/el2/base/haps/entry/image.png", 516 mimeType : "image/*", 517 relativePath : "Pictures/" 518}; 519mediaLibrary.getMediaLibrary().storeMediaAsset(option).then((value) => { 520 console.log("Media asset stored."); 521 // Obtain the URI that stores the media asset. 522}).catch((err) => { 523 console.log("An error occurred when storing the media assets."); 524}); 525 ``` 526 527 528### startImagePreview<sup>(deprecated)</sup> 529 530startImagePreview(images: Array<string>, index: number, callback: AsyncCallback<void>): void 531 532Starts image preview, with the first image to preview specified. This API can be used to preview local images whose URIs start with **dataability://** or online images whose URIs start with **https://**. It uses an asynchronous callback to return the execution result. 533 534> **NOTE** 535> 536> This API is deprecated since API version 9. You are advised to use the **\<[Image](../arkui-ts/ts-basic-components-image.md)>** component instead. The **\<Image>** component can be used to render and display local and online images. 537 538**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 539 540**Parameters** 541 542| Name | Type | Mandatory | Description | 543| -------- | ------------------------- | ---- | ---------------------------------------- | 544| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **dataability://** or **https://**.| 545| index | number | Yes | Index of the first image to preview. | 546| callback | AsyncCallback<void> | Yes | Callback used to return the image preview result. If the preview fails, an error message is returned. | 547 548**Example** 549 550 ``` 551let images = [ 552 "dataability:///media/xxxx/2", 553 "dataability:///media/xxxx/3" 554]; 555/* Preview online images. 556let images = [ 557 "https://media.xxxx.com/image1.jpg", 558 "https://media.xxxx.com/image2.jpg" 559]; 560*/ 561let index = 1; 562mediaLibrary.getMediaLibrary().startImagePreview(images, index, (err) => { 563 if (err) { 564 console.log("An error occurred when previewing the images."); 565 return; 566 } 567 console.log("Succeeded in previewing the images."); 568}); 569 ``` 570 571 572### startImagePreview<sup>(deprecated)</sup> 573 574startImagePreview(images: Array<string>, callback: AsyncCallback<void>): void 575 576Starts image preview. This API can be used to preview local images whose URIs start with **dataability://** or online images whose URIs start with **https://**. It uses an asynchronous callback to return the execution result. 577 578> **NOTE** 579> 580> This API is deprecated since API version 9. You are advised to use the **\<[Image](../arkui-ts/ts-basic-components-image.md)>** component instead. The **\<Image>** component can be used to render and display local and online images. 581 582**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 583 584**Parameters** 585 586| Name | Type | Mandatory | Description | 587| -------- | ------------------------- | ---- | ---------------------------------------- | 588| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **https://** or **dataability://**.| 589| callback | AsyncCallback<void> | Yes | Callback used to return the image preview result. If the preview fails, an error message is returned. | 590 591**Example** 592 593 ``` 594let images = [ 595 "dataability:///media/xxxx/2", 596 "dataability:///media/xxxx/3" 597]; 598/* Preview online images. 599let images = [ 600 "https://media.xxxx.com/image1.jpg", 601 "https://media.xxxx.com/image2.jpg" 602]; 603*/ 604mediaLibrary.getMediaLibrary().startImagePreview(images, (err) => { 605 if (err) { 606 console.log("An error occurred when previewing the images."); 607 return; 608 } 609 console.log("Succeeded in previewing the images."); 610}); 611 ``` 612 613 614### startImagePreview<sup>(deprecated)</sup> 615 616startImagePreview(images: Array<string>, index?: number): Promise<void> 617 618Starts image preview, with the first image to preview specified. This API can be used to preview local images whose URIs start with dataability:// or online images whose URIs start with https://. It uses a promise to return the execution result. 619 620> **NOTE** 621> 622> This API is deprecated since API version 9. You are advised to use the **\<[Image](../arkui-ts/ts-basic-components-image.md)>** component instead. The **\<Image>** component can be used to render and display local and online images. 623 624**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 625 626**Parameters** 627 628| Name | Type | Mandatory | Description | 629| ------ | ------------------- | ---- | ---------------------------------------- | 630| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **dataability://** or **https://**.| 631| index | number | No | Index of the first image to preview. If this parameter is not specified, the default value **0** is used. | 632 633**Return value** 634 635| Type | Description | 636| ------------------- | ------------------------------- | 637| Promise<void> | Promise used to return the image preview result. If the preview fails, an error message is returned.| 638 639**Example** 640 641 ``` 642let images = [ 643 "dataability:///media/xxxx/2", 644 "dataability:///media/xxxx/3" 645]; 646/* Preview online images. 647let images = [ 648 "https://media.xxxx.com/image1.jpg", 649 "https://media.xxxx.com/image2.jpg" 650]; 651*/ 652let index = 1; 653mediaLibrary.getMediaLibrary().startImagePreview(images, index).then(() => { 654 console.log("Succeeded in previewing the images."); 655}).catch((err) => { 656 console.log("An error occurred when previewing the images."); 657}); 658 ``` 659 660 661### startMediaSelect<sup>(deprecated)</sup> 662 663startMediaSelect(option: MediaSelectOption, callback: AsyncCallback<Array<string>>): void 664 665Starts media selection. This API uses an asynchronous callback to return the list of URIs that store the selected media assets. 666 667> **NOTE** 668> 669> This API is deprecated since API version 9. You are advised to use the system app Gallery instead. Gallery is a built-in visual resource access application that provides features such as image and video management and browsing. For details about how to use Gallery, visit [OpenHarmony/applications_photos](https://gitee.com/openharmony/applications_photos). 670 671**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 672 673**Parameters** 674 675| Name | Type | Mandatory | Description | 676| -------- | ---------------------------------------- | ---- | ------------------------------------ | 677| option | [MediaSelectOption](#mediaselectoption) | Yes | Media selection option. | 678| callback | AsyncCallback<Array<string>> | Yes | Callback used to return the list of URIs (starting with **dataability://**) that store the selected media assets.| 679 680**Example** 681 682 ``` 683let option = { 684 type : "media", 685 count : 2 686}; 687mediaLibrary.getMediaLibrary().startMediaSelect(option, (err, value) => { 688 if (err) { 689 console.log("An error occurred when selecting the media asset."); 690 return; 691 } 692 console.log("Media asset selected."); 693 // Obtain the media selection value. 694}); 695 ``` 696 697 698### startMediaSelect<sup>(deprecated)</sup> 699 700startMediaSelect(option: MediaSelectOption): Promise<Array<string>> 701 702Starts media selection. This API uses a promise to return the list of URIs that store the selected media assets. 703 704> **NOTE** 705> 706> This API is deprecated since API version 9. You are advised to use the system app Gallery instead. Gallery is a built-in visual resource access application that provides features such as image and video management and browsing. For details about how to use Gallery, visit [OpenHarmony/applications_photos](https://gitee.com/openharmony/applications_photos). 707 708**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 709 710**Parameters** 711 712| Name | Type | Mandatory | Description | 713| ------ | --------------------------------------- | ---- | ------- | 714| option | [MediaSelectOption](#mediaselectoption) | Yes | Media selection option.| 715 716**Return value** 717 718| Type | Description | 719| ---------------------------------- | ---------------------------------------- | 720| Promise<Array<string>> | Promise used to return the list of URIs (starting with **dataability://**) that store the selected media assets.| 721 722**Example** 723 724 ``` 725let option = { 726 type : "media", 727 count : 2 728}; 729mediaLibrary.getMediaLibrary().startMediaSelect(option).then((value) => { 730 console.log("Media asset selected."); 731 // Obtain the media selection value. 732}).catch((err) => { 733 console.log("An error occurred when selecting the media assets."); 734}); 735 736 ``` 737 738## FileAsset<sup>7+</sup> 739 740Provides APIs for encapsulating file asset attributes. 741 742### Attributes 743 744**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 745 746| Name | Type | Readable| Writable| Description | 747| ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | 748| id | number | Yes | No | File asset ID. | 749| uri | string | Yes | No | File asset URI, for example, **dataability:///media/image/2**. | 750| mimeType | string | Yes | No | Extended file attributes. | 751| mediaType<sup>8+</sup> | [MediaType](#mediatype8) | Yes | No | Media type. | 752| displayName | string | Yes | Yes | Display file name, including the file name extension. | 753| title | string | Yes | Yes | Title in the file. | 754| relativePath<sup>8+</sup> | string | Yes | Yes | Relative public directory of the file. | 755| parent<sup>8+</sup> | number | Yes | No | Parent directory ID. | 756| size | number | Yes | No | File size, in bytes. | 757| dateAdded | number | Yes | No | Date when the file was added. (The value is the number of seconds elapsed since the Epoch time.) | 758| dateModified | number | Yes | No | Date when the file was modified. (The value is the number of seconds elapsed since the Epoch time.) | 759| dateTaken | number | Yes | No | Date when the file (photo) was taken. (The value is the number of seconds elapsed since the Epoch time.) | 760| artist<sup>8+</sup> | string | Yes | No | Artist of the file. | 761| audioAlbum<sup>8+</sup> | string | Yes | No | Audio album. | 762| width | number | Yes | No | Image width, in pixels. | 763| height | number | Yes | No | Image height, in pixels. | 764| orientation | number | Yes | Yes | Image display direction (clockwise rotation angle, for example, 0, 90, or 180, in degrees).| 765| duration<sup>8+</sup> | number | Yes | No | Duration, in ms. | 766| albumId | number | Yes | No | ID of the album to which the file belongs. | 767| albumUri<sup>8+</sup> | string | Yes | No | URI of the album to which the file belongs. | 768| albumName | string | Yes | No | Name of the album to which the file belongs. | 769 770 771### isDirectory<sup>8+</sup> 772 773isDirectory(callback: AsyncCallback<boolean>): void 774 775Checks whether this file asset is a directory. This API uses an asynchronous callback to return the result. 776 777**Required permissions**: ohos.permission.READ_MEDIA 778 779**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 780 781**Parameters** 782 783| Name | Type | Mandatory | Description | 784| -------- | ---------------------------- | ---- | ------------------- | 785| callback | AsyncCallback<boolean> | Yes | Callback used to return whether the file asset is a directory.| 786 787**Example** 788 789``` 790async function example() { 791 let fileKeyObj = mediaLibrary.FileKey 792 let imageType = mediaLibrary.MediaType.IMAGE; 793 let getImageOp = { 794 selections: fileKeyObj.MEDIA_TYPE + '= ?', 795 selectionArgs: [imageType.toString()], 796 order: fileKeyObj.DATE_ADDED + " DESC", 797 extendArgs: "", 798 }; 799 const fetchFileResult = await media.getFileAssets(getImageOp); 800 const asset = await fetchFileResult.getFirstObject(); 801 asset.isDirectory((err, isDirectory) => { 802 // do something 803 }); 804} 805``` 806 807### isDirectory<sup>8+</sup> 808 809isDirectory():Promise<boolean> 810 811Checks whether this file asset is a directory. This API uses a promise to return the result. 812 813**Required permissions**: ohos.permission.READ_MEDIA 814 815**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 816 817**Return value** 818 819| Type | Description | 820| ---------------------- | ---------------------------- | 821| Promise<boolean> | Promise used to return whether the file asset is a directory.| 822 823**Example** 824 825``` 826async function example() { 827 let fileKeyObj = mediaLibrary.FileKey 828 let imageType = mediaLibrary.MediaType.IMAGE; 829 let getImageOp = { 830 selections: fileKeyObj.MEDIA_TYPE + '= ?', 831 selectionArgs: [imageType.toString()], 832 order: fileKeyObj.DATE_ADDED + " DESC", 833 extendArgs: "", 834 }; 835 const fetchFileResult = await media.getFileAssets(getImageOp); 836 const asset = await fetchFileResult.getFirstObject(); 837 asset.isDirectory().then(function(isDirectory){ 838 console.info("isDirectory result:"+ isDirectory); 839 }).catch(function(err){ 840 console.info("isDirectory failed with error:"+ err); 841 }); 842} 843``` 844 845### commitModify<sup>8+</sup> 846 847commitModify(callback: AsyncCallback<void>): void 848 849Commits the modification in this file asset to the database. This API uses an asynchronous callback to return the result. 850 851**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 852 853**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 854 855**Parameters** 856 857| Name | Type | Mandatory | Description | 858| -------- | ------------------------- | ---- | ----- | 859| callback | AsyncCallback<void> | Yes | Void callback.| 860 861**Example** 862 863``` 864async function example() { 865 let fileKeyObj = mediaLibrary.FileKey 866 let imageType = mediaLibrary.MediaType.IMAGE; 867 let getImageOp = { 868 selections: fileKeyObj.MEDIA_TYPE + '= ?', 869 selectionArgs: [imageType.toString()], 870 order: fileKeyObj.DATE_ADDED + " DESC", 871 extendArgs: "", 872 }; 873 const fetchFileResult = await media.getFileAssets(getImageOp); 874 const asset = await fetchFileResult.getFirstObject(); 875 asset.title = 'newtitle'; 876 asset.commitModify(() => { 877 console.info('commitModify success'); 878 }); 879} 880``` 881 882### commitModify<sup>8+</sup> 883 884commitModify(): Promise<void> 885 886Commits the modification in this file asset to the database. This API uses a promise to return the result. 887 888**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 889 890**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 891 892**Return value** 893 894| Type | Description | 895| ------------------- | ---------- | 896| Promise<void> | Void promise.| 897 898**Example** 899 900``` 901async function example() { 902 let fileKeyObj = mediaLibrary.FileKey 903 let imageType = mediaLibrary.MediaType.IMAGE; 904 let getImageOp = { 905 selections: fileKeyObj.MEDIA_TYPE + '= ?', 906 selectionArgs: [imageType.toString()], 907 order: fileKeyObj.DATE_ADDED + " DESC", 908 extendArgs: "", 909 }; 910 const fetchFileResult = await media.getFileAssets(getImageOp); 911 const asset = await fetchFileResult.getFirstObject(); 912 asset.title = 'newtitle'; 913 asset.commitModify(); 914} 915``` 916 917### open<sup>8+</sup> 918 919open(mode: string, callback: AsyncCallback<number>): void 920 921Opens this file asset. This API uses an asynchronous callback to return the result. 922 923> **NOTE** 924> 925> Currently, the write operations are mutually exclusive. After the write operation is complete, you must call **close** to release the resource. 926 927**Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA 928 929**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 930 931**Parameters** 932 933| Name | Type | Mandatory | Description | 934| -------- | --------------------------- | ---- | ----------------------------------- | 935| mode | string | Yes | Mode of opening the file, for example, **'r'** (read-only), **'w'** (write-only), and **'rw'** (read-write).| 936| callback | AsyncCallback<number> | Yes | Callback used to return the file handle. | 937 938**Example** 939 940``` 941async function example() { 942 let mediaType = mediaLibrary.MediaType.IMAGE; 943 let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; 944 const path = await media.getPublicDirectory(DIR_IMAGE); 945 const asset = await media.createAsset(mediaType, "image00003.jpg", path); 946 asset.open('rw', (openError, fd) => { 947 if(fd > 0){ 948 asset.close(fd); 949 }else{ 950 console.info('File Open Failed!' + openError); 951 } 952 }); 953} 954``` 955 956### open<sup>8+</sup> 957 958open(mode: string): Promise<number> 959 960Opens this file asset. This API uses a promise to return the result. 961 962> **NOTE** 963> 964> Currently, the write operations are mutually exclusive. After the write operation is complete, you must call **close** to release the resource. 965 966**Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA 967 968**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 969 970**Parameters** 971 972| Name | Type | Mandatory | Description | 973| ---- | ------ | ---- | ----------------------------------- | 974| mode | string | Yes | Mode of opening the file, for example, **'r'** (read-only), **'w'** (write-only), and **'rw'** (read-write).| 975 976**Return value** 977 978| Type | Description | 979| --------------------- | ------------- | 980| Promise<number> | Promise used to return the file handle.| 981 982**Example** 983 984``` 985async function example() { 986 let mediaType = mediaLibrary.MediaType.IMAGE; 987 let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; 988 const path = await media.getPublicDirectory(DIR_IMAGE); 989 const asset = await media.createAsset(mediaType, "image00003.jpg", path); 990 asset.open('rw') 991 .then((fd) => { 992 console.info('File fd!' + fd); 993 }) 994 .catch((err) => { 995 console.info('File err!' + err); 996 }); 997} 998``` 999 1000### close<sup>8+</sup> 1001 1002close(fd: number, callback: AsyncCallback<void>): void 1003 1004Closes this file asset. This API uses an asynchronous callback to return the result. 1005 1006**Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA 1007 1008**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1009 1010**Parameters** 1011 1012| Name | Type | Mandatory | Description | 1013| -------- | ------------------------- | ---- | ----- | 1014| fd | number | Yes | File descriptor.| 1015| callback | AsyncCallback<void> | Yes | Void callback.| 1016 1017**Example** 1018 1019``` 1020async function example() { 1021 let fileKeyObj = mediaLibrary.FileKey 1022 let imageType = mediaLibrary.MediaType.IMAGE; 1023 let getImageOp = { 1024 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1025 selectionArgs: [imageType.toString()], 1026 order: fileKeyObj.DATE_ADDED + " DESC", 1027 extendArgs: "", 1028 }; 1029 const fetchFileResult = await media.getFileAssets(getImageOp); 1030 const asset = await fetchFileResult.getFirstObject(); 1031 asset.open('rw').then((fd) => { 1032 console.info('File fd!' + fd); 1033 asset.close(fd, (closeErr) => { 1034 if (closeErr != undefined) { 1035 console.info('mediaLibraryTest : close : FAIL ' + closeErr.message); 1036 console.info('mediaLibraryTest : ASSET_CALLBACK : FAIL'); 1037 } else { 1038 console.info("=======asset.close success====>"); 1039 } 1040 }); 1041 }) 1042 .catch((err) => { 1043 console.info('File err!' + err); 1044 }); 1045} 1046``` 1047 1048### close<sup>8+</sup> 1049 1050close(fd: number): Promise<void> 1051 1052Closes this file asset. This API uses a promise to return the result. 1053 1054**Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA 1055 1056**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1057 1058**Parameters** 1059 1060| Name | Type | Mandatory | Description | 1061| ---- | ------ | ---- | ----- | 1062| fd | number | Yes | File descriptor.| 1063 1064**Return value** 1065 1066| Type | Description | 1067| ------------------- | ---------- | 1068| Promise<void> | Void promise.| 1069 1070**Example** 1071 1072``` 1073async function example() { 1074 let fileKeyObj = mediaLibrary.FileKey 1075 let imageType = mediaLibrary.MediaType.IMAGE; 1076 let getImageOp = { 1077 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1078 selectionArgs: [imageType.toString()], 1079 order: fileKeyObj.DATE_ADDED + " DESC", 1080 extendArgs: "", 1081 }; 1082 const fetchFileResult = await media.getFileAssets(getImageOp); 1083 const asset = await fetchFileResult.getFirstObject(); 1084 asset.open('rw').then((fd) => { 1085 console.info('File fd!' + fd); 1086 asset.close(fd).then((closeErr) => { 1087 if (closeErr != undefined) { 1088 console.info('mediaLibraryTest : close : FAIL ' + closeErr.message); 1089 console.info('mediaLibraryTest : ASSET_CALLBACK : FAIL'); 1090 1091 } else { 1092 console.info("=======asset.close success====>"); 1093 } 1094 }); 1095 }) 1096 .catch((err) => { 1097 console.info('File err!' + err); 1098 }); 1099} 1100``` 1101 1102### getThumbnail<sup>8+</sup> 1103 1104getThumbnail(callback: AsyncCallback<image.PixelMap>): void 1105 1106Obtains the thumbnail of this file asset. This API uses an asynchronous callback to return the result. 1107 1108**Required permissions**: ohos.permission.READ_MEDIA 1109 1110**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1111 1112**Parameters** 1113 1114| Name | Type | Mandatory | Description | 1115| -------- | ----------------------------------- | ---- | ---------------- | 1116| callback | AsyncCallback<image.PixelMap> | Yes | Callback used to return the pixel map of the thumbnail.| 1117 1118**Example** 1119 1120``` 1121async function example() { 1122 let fileKeyObj = mediaLibrary.FileKey 1123 let imageType = mediaLibrary.MediaType.IMAGE; 1124 let getImageOp = { 1125 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1126 selectionArgs: [imageType.toString()], 1127 order: fileKeyObj.DATE_ADDED + " DESC", 1128 extendArgs: "", 1129 }; 1130 const fetchFileResult = await media.getFileAssets(getImageOp); 1131 const asset = await fetchFileResult.getFirstObject(); 1132 asset.getThumbnail((err, pixelmap) => { 1133 console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); 1134 }); 1135} 1136``` 1137 1138### getThumbnail<sup>8+</sup> 1139 1140getThumbnail(size: Size, callback: AsyncCallback<image.PixelMap>): void 1141 1142Obtains the thumbnail of this file asset, with the thumbnail size passed. This API uses an asynchronous callback to return the result. 1143 1144**Required permissions**: ohos.permission.READ_MEDIA 1145 1146**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1147 1148**Parameters** 1149 1150| Name | Type | Mandatory | Description | 1151| -------- | ----------------------------------- | ---- | ---------------- | 1152| size | [Size](#size8) | Yes | Size of the thumbnail. | 1153| callback | AsyncCallback<image.PixelMap> | Yes | Callback used to return the pixel map of the thumbnail.| 1154 1155**Example** 1156 1157``` 1158async function example() { 1159 let fileKeyObj = mediaLibrary.FileKey 1160 let imageType = mediaLibrary.MediaType.IMAGE; 1161 let getImageOp = { 1162 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1163 selectionArgs: [imageType.toString()], 1164 order: fileKeyObj.DATE_ADDED + " DESC", 1165 extendArgs: "", 1166 }; 1167 let size = { width: 720, height: 720 }; 1168 const fetchFileResult = await media.getFileAssets(getImageOp); 1169 const asset = await fetchFileResult.getFirstObject(); 1170 asset.getThumbnail(size, (err, pixelmap) => { 1171 console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); 1172 }); 1173} 1174``` 1175 1176### getThumbnail<sup>8+</sup> 1177 1178getThumbnail(size?: Size): Promise<image.PixelMap> 1179 1180Obtains the thumbnail of this file asset, with the thumbnail size passed. This API uses a promise to return the result. 1181 1182**Required permissions**: ohos.permission.READ_MEDIA 1183 1184**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1185 1186**Parameters** 1187 1188| Name | Type | Mandatory | Description | 1189| ---- | -------------- | ---- | ----- | 1190| size | [Size](#size8) | No | Size of the thumbnail.| 1191 1192**Return value** 1193 1194| Type | Description | 1195| ----------------------------- | --------------------- | 1196| Promise<image.PixelMap> | Promise to return the pixel map of the thumbnail.| 1197 1198**Example** 1199 1200``` 1201async function example() { 1202 let fileKeyObj = mediaLibrary.FileKey 1203 let imageType = mediaLibrary.MediaType.IMAGE; 1204 let getImageOp = { 1205 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1206 selectionArgs: [imageType.toString()], 1207 order: fileKeyObj.DATE_ADDED + " DESC", 1208 extendArgs: "", 1209 }; 1210 let size = { width: 720, height: 720 }; 1211 const fetchFileResult = await media.getFileAssets(getImageOp); 1212 const asset = await fetchFileResult.getFirstObject(); 1213 asset.getThumbnail(size) 1214 .then((pixelmap) => { 1215 console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); 1216 }) 1217 .catch((err) => { 1218 console.info('mediaLibraryTest : getThumbnail fail'+ err); 1219 }); 1220} 1221``` 1222 1223### favorite<sup>8+</sup> 1224 1225favorite(isFavorite: boolean, callback: AsyncCallback<void>): void 1226 1227Favorites or unfavorites this file asset. This API uses an asynchronous callback to return the result. 1228 1229**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 1230 1231**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1232 1233**Parameters** 1234 1235| Name | Type | Mandatory | Description | 1236| ---------- | ------------------------- | ---- | ---------------------------------- | 1237| isFavorite | boolean | Yes | Whether to favorite or unfavorite the file. The value **true** means to favorite the file, and **false** means to unfavorite the file.| 1238| callback | AsyncCallback<void> | Yes | Void callback. | 1239 1240**Example** 1241 1242``` 1243async function example() { 1244 let fileKeyObj = mediaLibrary.FileKey 1245 let imageType = mediaLibrary.MediaType.IMAGE; 1246 let getImageOp = { 1247 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1248 selectionArgs: [imageType.toString()], 1249 order: fileKeyObj.DATE_ADDED + " DESC", 1250 extendArgs: "", 1251 }; 1252 const fetchFileResult = await media.getFileAssets(getImageOp); 1253 const asset = await fetchFileResult.getFirstObject(); 1254 asset.favorite(true,function(err){ 1255 // do something 1256 }); 1257} 1258``` 1259 1260### favorite<sup>8+</sup> 1261 1262favorite(isFavorite: boolean): Promise<void> 1263 1264Favorites or unfavorites this file asset. This API uses a promise to return the result. 1265 1266**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 1267 1268**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1269 1270**Parameters** 1271 1272| Name | Type | Mandatory | Description | 1273| ---------- | ------- | ---- | ---------------------------------- | 1274| isFavorite | boolean | Yes | Whether to favorite or unfavorite the file. The value **true** means to favorite the file, and **false** means to unfavorite the file.| 1275 1276**Return value** 1277 1278| Type | Description | 1279| ------------------- | ---------- | 1280| Promise<void> | Void promise.| 1281 1282**Example** 1283 1284``` 1285async function example() { 1286 let fileKeyObj = mediaLibrary.FileKey 1287 let imageType = mediaLibrary.MediaType.IMAGE; 1288 let getImageOp = { 1289 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1290 selectionArgs: [imageType.toString()], 1291 order: fileKeyObj.DATE_ADDED + " DESC", 1292 extendArgs: "", 1293 }; 1294 const fetchFileResult = await media.getFileAssets(getImageOp); 1295 const asset = await fetchFileResult.getFirstObject(); 1296 asset.favorite(true).then(function() { 1297 console.info("favorite successfully"); 1298 }).catch(function(err){ 1299 console.info("favorite failed with error:"+ err); 1300 }); 1301} 1302``` 1303 1304### isFavorite<sup>8+</sup> 1305 1306isFavorite(callback: AsyncCallback<boolean>): void 1307 1308Checks whether this file asset is favorited. This API uses an asynchronous callback to return the result. 1309 1310**Required permissions**: ohos.permission.READ_MEDIA 1311 1312**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1313 1314**Parameters** 1315 1316| Name | Type | Mandatory | Description | 1317| -------- | ---------------------------- | ---- | ----------- | 1318| callback | AsyncCallback<boolean> | Yes | Callback used to return whether the file asset is favorited.| 1319 1320**Example** 1321 1322``` 1323async function example() { 1324 let fileKeyObj = mediaLibrary.FileKey 1325 let imageType = mediaLibrary.MediaType.IMAGE; 1326 let getImageOp = { 1327 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1328 selectionArgs: [imageType.toString()], 1329 order: fileKeyObj.DATE_ADDED + " DESC", 1330 extendArgs: "", 1331 }; 1332 const fetchFileResult = await media.getFileAssets(getImageOp); 1333 const asset = await fetchFileResult.getFirstObject(); 1334 asset.isFavorite((err, isFavorite) => { 1335 if (isFavorite) { 1336 console.info('FileAsset is favorite'); 1337 }else{ 1338 console.info('FileAsset is not favorite'); 1339 } 1340 }); 1341} 1342``` 1343 1344### isFavorite<sup>8+</sup> 1345 1346isFavorite():Promise<boolean> 1347 1348Checks whether this file asset is favorited. This API uses a promise to return the result. 1349 1350**Required permissions**: ohos.permission.READ_MEDIA 1351 1352**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1353 1354**Return value** 1355 1356| Type | Description | 1357| ---------------------- | ------------------ | 1358| Promise<boolean> | Promise used to return whether the file asset is favorited.| 1359 1360**Example** 1361 1362``` 1363async function example() { 1364 let fileKeyObj = mediaLibrary.FileKey 1365 let imageType = mediaLibrary.MediaType.IMAGE; 1366 let getImageOp = { 1367 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1368 selectionArgs: [imageType.toString()], 1369 order: fileKeyObj.DATE_ADDED + " DESC", 1370 extendArgs: "", 1371 }; 1372 const fetchFileResult = await media.getFileAssets(getImageOp); 1373 const asset = await fetchFileResult.getFirstObject(); 1374 asset.isFavorite().then(function(isFavorite){ 1375 console.info("isFavorite result:"+ isFavorite); 1376 }).catch(function(err){ 1377 console.info("isFavorite failed with error:"+ err); 1378 }); 1379} 1380``` 1381 1382### trash<sup>8+</sup> 1383 1384trash(isTrash: boolean, callback: AsyncCallback<void>): void 1385 1386Moves this file asset to the trash. This API uses an asynchronous callback to return the result. 1387 1388Files in the trash are not actually deleted. You can set **isTrash** to **false** to restore the files from the trash. 1389 1390**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 1391 1392**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1393 1394**Parameters** 1395 1396| Name | Type | Mandatory | Description | 1397| -------- | ------------------------- | ---- | --------- | 1398| isTrash | boolean | Yes | Whether to move the file asset to the trash. The value **true** means to move the file asset to the trash, and **false** means the opposite.| 1399| callback | AsyncCallback<void> | Yes | Void callback. | 1400 1401**Example** 1402 1403``` 1404async function example() { 1405 let fileKeyObj = mediaLibrary.FileKey 1406 let imageType = mediaLibrary.MediaType.IMAGE; 1407 let getImageOp = { 1408 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1409 selectionArgs: [imageType.toString()], 1410 order: fileKeyObj.DATE_ADDED + " DESC", 1411 extendArgs: "", 1412 }; 1413 const fetchFileResult = await media.getFileAssets(getImageOp); 1414 const asset = await fetchFileResult.getFirstObject(); 1415 asset.trash(true, trashCallBack); 1416 function trashCallBack(err, trash) { 1417 console.info('mediaLibraryTest : ASSET_CALLBACK ASSET_CALLBACK trash'); 1418 } 1419} 1420``` 1421 1422### trash<sup>8+</sup> 1423 1424trash(isTrash: boolean): Promise<void> 1425 1426Moves this file asset to the trash. This API uses a promise to return the result. 1427 1428Files in the trash are not actually deleted. You can set **isTrash** to **false** to restore the files from the trash. 1429 1430**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 1431 1432**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1433 1434**Parameters** 1435 1436| Name | Type | Mandatory | Description | 1437| ------- | ------- | ---- | --------- | 1438| isTrash | boolean | Yes | Whether to move the file asset to the trash. The value **true** means to move the file asset to the trash, and **false** means the opposite.| 1439 1440**Return value** 1441 1442| Type | Description | 1443| ------------------- | ---------- | 1444| Promise<void> | Void promise.| 1445 1446**Example** 1447 1448``` 1449async function example() { 1450 let fileKeyObj = mediaLibrary.FileKey 1451 let imageType = mediaLibrary.MediaType.IMAGE; 1452 let getImageOp = { 1453 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1454 selectionArgs: [imageType.toString()], 1455 order: fileKeyObj.DATE_ADDED + " DESC", 1456 extendArgs: "", 1457 }; 1458 const fetchFileResult = await media.getFileAssets(getImageOp); 1459 const asset = await fetchFileResult.getFirstObject(); 1460 asset.trash(true).then(function() { 1461 console.info("trash successfully"); 1462 }).catch(function(err){ 1463 console.info("trash failed with error:"+ err); 1464 }); 1465} 1466``` 1467 1468### isTrash<sup>8+</sup> 1469 1470isTrash(callback: AsyncCallback<boolean>): void 1471 1472Checks whether this file asset is in the trash. This API uses an asynchronous callback to return the result. 1473 1474**Required permissions**: ohos.permission.READ_MEDIA 1475 1476**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1477 1478**Parameters** 1479 1480| Name | Type | Mandatory | Description | 1481| -------- | ---------------------------- | ---- | --------------- | 1482| callback | AsyncCallback<boolean> | Yes | Callback used to return whether the file asset is in the trash. If the file asset is in the trash, **true** will be returned; otherwise, **false** will be returned.| 1483 1484**Example** 1485 1486``` 1487async function example() { 1488 let fileKeyObj = mediaLibrary.FileKey 1489 let imageType = mediaLibrary.MediaType.IMAGE; 1490 let getImageOp = { 1491 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1492 selectionArgs: [imageType.toString()], 1493 order: fileKeyObj.DATE_ADDED + " DESC", 1494 extendArgs: "", 1495 }; 1496 const fetchFileResult = await media.getFileAssets(getImageOp); 1497 const asset = await fetchFileResult.getFirstObject(); 1498 asset.isTrash(isTrashCallBack); 1499 function isTrashCallBack(err, isTrash) { 1500 if (isTrash == true) { 1501 console.info('mediaLibraryTest : ASSET_CALLBACK ASSET_CALLBACK isTrash = ' + isTrash); 1502 asset.trash(true, istrashCallBack); 1503 1504 } else { 1505 console.info('mediaLibraryTest : ASSET_CALLBACK isTrash Unsuccessfull = ' + err); 1506 console.info('mediaLibraryTest : ASSET_CALLBACK isTrash : FAIL'); 1507 1508 } 1509 } 1510} 1511``` 1512 1513### isTrash<sup>8+</sup> 1514 1515isTrash():Promise<boolean> 1516 1517Checks whether this file asset is in the trash. This API uses a promise to return the result. 1518 1519**Required permissions**: ohos.permission.READ_MEDIA 1520 1521**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1522 1523**Return value** 1524 1525| Type | Description | 1526| ------------------- | -------------------- | 1527| Promise<void> | Promise used to return whether the file asset is in the trash. If the file asset is in the trash, **true** will be returned; otherwise, **false** will be returned.| 1528 1529**Example** 1530 1531``` 1532async function example() { 1533 let fileKeyObj = mediaLibrary.FileKey 1534 let imageType = mediaLibrary.MediaType.IMAGE; 1535 let getImageOp = { 1536 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1537 selectionArgs: [imageType.toString()], 1538 order: fileKeyObj.DATE_ADDED + " DESC", 1539 extendArgs: "", 1540 }; 1541 const fetchFileResult = await media.getFileAssets(getImageOp); 1542 const asset = await fetchFileResult.getFirstObject(); 1543 asset.isTrash().then(function(isTrash){ 1544 console.info("isTrash result:"+ isTrash); 1545 }).catch(function(err){ 1546 console.info("isTrash failed with error:"+ err); 1547 }); 1548} 1549``` 1550 1551## FetchFileResult<sup>7+</sup> 1552 1553Implements the result set of the file retrieval operation. 1554 1555### getCount<sup>7+</sup> 1556 1557getCount(): number 1558 1559Obtains the total number of files in the result set. 1560 1561**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1562 1563**Return value** 1564 1565| Type | Description | 1566| ------ | -------- | 1567| number | Total number of files.| 1568 1569**Example** 1570 1571``` 1572async function example() { 1573 let fileKeyObj = mediaLibrary.FileKey 1574 let fileType = mediaLibrary.MediaType.FILE; 1575 let getFileCountOneOp = { 1576 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1577 selectionArgs: [fileType.toString()], 1578 order: fileKeyObj.DATE_ADDED + " DESC", 1579 extendArgs: "", 1580 }; 1581 let fetchFileResult = await media.getFileAssets(getFileCountOneOp); 1582 const fetchCount = fetchFileResult.getCount(); 1583} 1584``` 1585 1586### isAfterLast<sup>7+</sup> 1587 1588isAfterLast(): boolean 1589 1590Checks whether the cursor is in the last row of the result set. 1591 1592**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1593 1594**Return value** 1595 1596| Type | Description | 1597| ------- | ---------------------------------- | 1598| boolean | Returns **true** if the cursor is in the last row of the result set; returns *false* otherwise.| 1599 1600**Example** 1601 1602``` 1603async function example() { 1604 let fileKeyObj = mediaLibrary.FileKey 1605 let imageType = mediaLibrary.MediaType.IMAGE; 1606 let getImageOp = { 1607 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1608 selectionArgs: [imageType.toString()], 1609 order: fileKeyObj.DATE_ADDED + " DESC", 1610 extendArgs: "", 1611 }; 1612 let fetchFileResult = await media.getFileAssets(getImageOp); 1613 const fetchCount = fetchFileResult.getCount(); 1614 console.info('mediaLibraryTest : count:' + fetchCount); 1615 let fileAsset = await fetchFileResult.getFirstObject(); 1616 for (var i = 1; i < fetchCount; i++) { 1617 fileAsset = await fetchFileResult.getNextObject(); 1618 if(i == fetchCount - 1) { 1619 console.info('mediaLibraryTest : isLast'); 1620 var result = fetchFileResult.isAfterLast(); 1621 console.info('mediaLibraryTest : isAfterLast:' + result); 1622 console.info('mediaLibraryTest : isAfterLast end'); 1623 fetchFileResult.close(); 1624 1625 } 1626 } 1627} 1628``` 1629 1630### close<sup>7+</sup> 1631 1632close(): void 1633 1634Releases and invalidates this **FetchFileResult** instance. Other APIs in this instance cannot be invoked after it is released. 1635 1636**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1637 1638**Example** 1639 1640``` 1641async function example() { 1642 let fileKeyObj = mediaLibrary.FileKey 1643 let imageType = mediaLibrary.MediaType.IMAGE; 1644 let getImageOp = { 1645 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1646 selectionArgs: [imageType.toString()], 1647 order: fileKeyObj.DATE_ADDED + " DESC", 1648 extendArgs: "", 1649 }; 1650 let fetchFileResult = await media.getFileAssets(getImageOp); 1651 fetchFileResult.close(); 1652} 1653``` 1654 1655### getFirstObject<sup>7+</sup> 1656 1657getFirstObject(callback: AsyncCallback<FileAsset>): void 1658 1659Obtains the first file asset in the result set. This API uses an asynchronous callback to return the result. 1660 1661**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1662 1663**Parameters** 1664 1665| Name | Type | Mandatory| Description | 1666| -------- | --------------------------------------------- | ---- | ------------------------------------------- | 1667| callback | AsyncCallback<[FileAsset](#fileasset7)> | Yes | Callback used to return the first file asset.| 1668 1669**Example** 1670 1671``` 1672async function example() { 1673 let fileKeyObj = mediaLibrary.FileKey 1674 let imageType = mediaLibrary.MediaType.IMAGE; 1675 let getImageOp = { 1676 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1677 selectionArgs: [imageType.toString()], 1678 order: fileKeyObj.DATE_ADDED + " DESC", 1679 extendArgs: "", 1680 }; 1681 let fetchFileResult = await media.getFileAssets(getImageOp); 1682 fetchFileResult.getFirstObject((err, fileAsset) => { 1683 if (err) { 1684 console.error('Failed '); 1685 return; 1686 } 1687 console.log('fileAsset.displayName : ' + fileAsset.displayName); 1688 }) 1689} 1690``` 1691 1692### getFirstObject<sup>7+</sup> 1693 1694getFirstObject(): Promise<FileAsset> 1695 1696Obtains the first file asset in the result set. This API uses a promise to return the result. 1697 1698**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1699 1700**Return value** 1701 1702| Type | Description | 1703| --------------------------------------- | -------------------------- | 1704| Promise<[FileAsset](#fileasset7)> | Promise used to return the file asset.| 1705 1706**Example** 1707 1708``` 1709async function example() { 1710 let fileKeyObj = mediaLibrary.FileKey 1711 let imageType = mediaLibrary.MediaType.IMAGE; 1712 let getImageOp = { 1713 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1714 selectionArgs: [imageType.toString()], 1715 order: fileKeyObj.DATE_ADDED + " DESC", 1716 extendArgs: "", 1717 }; 1718 let fetchFileResult = await media.getFileAssets(getImageOp); 1719 fetchFileResult.getFirstObject().then(function(fileAsset){ 1720 console.info("getFirstObject successfully:"+ JSON.stringify(fileAsset)); 1721 }).catch(function(err){ 1722 console.info("getFirstObject failed with error:"+ err); 1723 }); 1724} 1725``` 1726 1727### getNextObject<sup>7+</sup> 1728 1729 getNextObject(callback: AsyncCallback<FileAsset>): void 1730 1731Obtains the next file asset in the result set. This API uses an asynchronous callback to return the result. 1732 1733**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1734 1735**Parameters** 1736 1737| Name | Type | Mandatory| Description | 1738| --------- | --------------------------------------------- | ---- | ----------------------------------------- | 1739| callbacke | AsyncCallback<[FileAsset](#fileasset7)> | Yes | Callback used to return the next file asset.| 1740 1741**Example** 1742 1743``` 1744async function example() { 1745 let fileKeyObj = mediaLibrary.FileKey 1746 let imageType = mediaLibrary.MediaType.IMAGE; 1747 let getImageOp = { 1748 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1749 selectionArgs: [imageType.toString()], 1750 order: fileKeyObj.DATE_ADDED + " DESC", 1751 extendArgs: "", 1752 }; 1753 let fetchFileResult = await media.getFileAssets(getImageOp); 1754 fetchFileResult.getNextObject((err, fileAsset) => { 1755 if (err) { 1756 console.error('Failed '); 1757 return; 1758 } 1759 console.log('fileAsset.displayName : ' + fileAsset.displayName); 1760 }) 1761} 1762``` 1763 1764### getNextObject<sup>7+</sup> 1765 1766 getNextObject(): Promise<FileAsset> 1767 1768Obtains the next file asset in the result set. This API uses a promise to return the result. 1769 1770**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1771 1772**Return value** 1773 1774| Type | Description | 1775| --------------------------------------- | ----------------- | 1776| Promise<[FileAsset](#fileasset7)> | Promise used to return the next file asset.| 1777 1778**Example** 1779 1780``` 1781async function example() { 1782 let fileKeyObj = mediaLibrary.FileKey 1783 let imageType = mediaLibrary.MediaType.IMAGE; 1784 let getImageOp = { 1785 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1786 selectionArgs: [imageType.toString()], 1787 order: fileKeyObj.DATE_ADDED + " DESC", 1788 extendArgs: "", 1789 }; 1790 let fetchFileResult = await media.getFileAssets(getImageOp); 1791 const fetchCount = fetchFileResult.getCount(); 1792 console.info('mediaLibraryTest : count:' + fetchCount); 1793 let fileAsset = await fetchFileResult.getNextObject(); 1794} 1795``` 1796 1797### getLastObject<sup>7+</sup> 1798 1799getLastObject(callback: AsyncCallback<FileAsset>): void 1800 1801Obtains the last file asset in the result set. This API uses an asynchronous callback to return the result. 1802 1803**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1804 1805**Parameters** 1806 1807| Name | Type | Mandatory| Description | 1808| -------- | --------------------------------------------- | ---- | --------------------------- | 1809| callback | AsyncCallback<[FileAsset](#fileasset7)> | Yes | Callback used to return the last file asset.| 1810 1811**Example** 1812 1813``` 1814async function example() { 1815 let fileKeyObj = mediaLibrary.FileKey 1816 let imageType = mediaLibrary.MediaType.IMAGE; 1817 let getImageOp = { 1818 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1819 selectionArgs: [imageType.toString()], 1820 order: fileKeyObj.DATE_ADDED + " DESC", 1821 extendArgs: "", 1822 }; 1823 let fetchFileResult = await media.getFileAssets(getImageOp); 1824 fetchFileResult.getLastObject((err, fileAsset) => { 1825 if (err) { 1826 console.error('Failed '); 1827 return; 1828 } 1829 console.log('fileAsset.displayName : ' + fileAsset.displayName); 1830 }) 1831} 1832``` 1833 1834### getLastObject<sup>7+</sup> 1835 1836getLastObject(): Promise<FileAsset> 1837 1838Obtains the last file asset in the result set. This API uses a promise to return the result. 1839 1840**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1841 1842**Return value** 1843 1844| Type | Description | 1845| --------------------------------------- | ----------------- | 1846| Promise<[FileAsset](#fileasset7)> | Promise used to return the next file asset.| 1847 1848**Example** 1849 1850``` 1851async function example() { 1852 let fileKeyObj = mediaLibrary.FileKey 1853 let imageType = mediaLibrary.MediaType.IMAGE; 1854 let getImageOp = { 1855 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1856 selectionArgs: [imageType.toString()], 1857 order: fileKeyObj.DATE_ADDED + " DESC", 1858 extendArgs: "", 1859 }; 1860 let fetchFileResult = await media.getFileAssets(getImageOp); 1861 let lastObject = await fetchFileResult.getLastObject(); 1862} 1863``` 1864 1865### getPositionObject<sup>7+</sup> 1866 1867getPositionObject(index: number, callback: AsyncCallback<FileAsset>): void 1868 1869Obtains a file asset with the specified index in the result set. This API uses an asynchronous callback to return the result. 1870 1871**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1872 1873**Parameters** 1874 1875| Name | Type | Mandatory | Description | 1876| -------- | ---------------------------------------- | ---- | ------------------ | 1877| index | number | Yes | Index of the file asset to obtain. The value starts from **0**. | 1878| callback | AsyncCallback<[FileAsset](#fileasset7)> | Yes | Callback used to return the last file asset.| 1879 1880**Example** 1881 1882``` 1883async function example() { 1884 let fileKeyObj = mediaLibrary.FileKey 1885 let imageType = mediaLibrary.MediaType.IMAGE; 1886 let getImageOp = { 1887 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1888 selectionArgs: [imageType.toString()], 1889 order: fileKeyObj.DATE_ADDED + " DESC", 1890 extendArgs: "", 1891 }; 1892 let fetchFileResult = await media.getFileAssets(getImageOp); 1893 fetchFileResult.getPositionObject(0, (err, fileAsset) => { 1894 if (err) { 1895 console.error('Failed '); 1896 return; 1897 } 1898 console.log('fileAsset.displayName : ' + fileAsset.displayName); 1899 }) 1900} 1901``` 1902 1903### getPositionObject<sup>7+</sup> 1904 1905getPositionObject(index: number): Promise<FileAsset> 1906 1907Obtains a file asset with the specified index in the result set. This API uses a promise to return the result. 1908 1909**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1910 1911**Parameters** 1912 1913| Name | Type | Mandatory | Description | 1914| ----- | ------ | ---- | -------------- | 1915| index | number | Yes | Index of the file asset to obtain. The value starts from **0**.| 1916 1917**Return value** 1918 1919| Type | Description | 1920| --------------------------------------- | ----------------- | 1921| Promise<[FileAsset](#fileasset7)> | Promise used to return the next file asset.| 1922 1923**Example** 1924 1925``` 1926async function example() { 1927 let fileKeyObj = mediaLibrary.FileKey 1928 let imageType = mediaLibrary.MediaType.IMAGE; 1929 let getImageOp = { 1930 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1931 selectionArgs: [imageType.toString()], 1932 order: fileKeyObj.DATE_ADDED + " DESC", 1933 extendArgs: "", 1934 }; 1935 let fetchFileResult = await media.getFileAssets(getImageOp); 1936 fetchFileResult.getPositionObject(1) .then(function (fileAsset){ 1937 console.log('[Demo] fileAsset.displayName : ' + fileAsset.displayName); 1938 }).catch(function (err) { 1939 console.info("[Demo] getFileAssets failed with error:" + err); 1940 }); 1941} 1942``` 1943 1944### getAllObject<sup>7+</sup> 1945 1946getAllObject(callback: AsyncCallback<Array<FileAsset>>): void 1947 1948Obtains all the file assets in the result set. This API uses an asynchronous callback to return the result. 1949 1950**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1951 1952**Parameters** 1953 1954| Name | Type | Mandatory | Description | 1955| -------- | ---------------------------------------- | ---- | -------------------- | 1956| callback | AsyncCallback<Array<[FileAsset](#fileasset7)>> | Yes | Callback used to return the file assets.| 1957 1958**Example** 1959 1960``` 1961async function example() { 1962 let fileKeyObj = mediaLibrary.FileKey 1963 let imageType = mediaLibrary.MediaType.IMAGE; 1964 let getImageOp = { 1965 selections: fileKeyObj.MEDIA_TYPE + '= ?', 1966 selectionArgs: [imageType.toString()], 1967 order: fileKeyObj.DATE_ADDED + " DESC", 1968 extendArgs: "", 1969 }; 1970 let fetchFileResult = await media.getFileAssets(getImageOp); 1971 fetchFileResult.getAllObject((err, fileAsset) => { 1972 if (err) { 1973 console.error('Failed '); 1974 return; 1975 } 1976 console.log('fileAsset.displayName : ' + fileAsset.displayName); 1977 }) 1978} 1979``` 1980 1981### getAllObject<sup>7+</sup> 1982 1983getAllObject(): Promise<Array<FileAsset>> 1984 1985Obtains all the file assets in the result set. This API uses a promise to return the result. 1986 1987**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 1988 1989**Return value** 1990 1991| Type | Description | 1992| ---------------------------------------- | --------------------- | 1993| Promise<Array<[FileAsset](#fileasset7)>> | Promise used to return the file assets.| 1994 1995**Example** 1996 1997``` 1998async function example() { 1999 let fileKeyObj = mediaLibrary.FileKey 2000 let imageType = mediaLibrary.MediaType.IMAGE; 2001 let getImageOp = { 2002 selections: fileKeyObj.MEDIA_TYPE + '= ?', 2003 selectionArgs: [imageType.toString()], 2004 order: fileKeyObj.DATE_ADDED + " DESC", 2005 extendArgs: "", 2006 }; 2007 let fetchFileResult = await media.getFileAssets(getImageOp); 2008 var data = fetchFileResult.getAllObject(); 2009} 2010``` 2011 2012## Album<sup>7+</sup> 2013 2014Provides APIs to implement a physical album. 2015 2016### Attributes 2017 2018**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2019 2020| Name | Type | Readable | Writable | Description | 2021| ------------ | ------ | ---- | ---- | ------- | 2022| albumId | number | Yes | No | Album ID. | 2023| albumName | string | Yes | Yes | Album name. | 2024| albumUri<sup>8+</sup> | string | Yes | No | Album URI. | 2025| dateModified | number | Yes | No | Date when the album was modified. | 2026| count<sup>8+</sup> | number | Yes | No | Number of files in the album.| 2027| relativePath<sup>8+</sup> | string | Yes | No | Relative path of the album. | 2028| coverUri<sup>8+</sup> | string | Yes | No | URI of the cover file of the album.| 2029 2030### commitModify<sup>8+</sup> 2031 2032commitModify(callback: AsyncCallback<void>): void 2033 2034Commits the modification in the album attributes to the database. This API uses an asynchronous callback to return the result. 2035 2036**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 2037 2038**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2039 2040**Parameters** 2041 2042| Name | Type | Mandatory| Description | 2043| -------- | ------------------------- | ---- | ---------- | 2044| callback | AsyncCallback<void> | Yes | Void callback.| 2045 2046**Example** 2047 2048``` 2049async function example() { 2050 let AlbumNoArgsfetchOp = { 2051 selections: '', 2052 selectionArgs: [], 2053 }; 2054 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); 2055 const album = albumList[0]; 2056 album.albumName = 'hello'; 2057 album.commitModify((err) => { 2058 if (err) { 2059 console.error('Failed '); 2060 return; 2061 } 2062 console.log('Modify successful.'); 2063 }) 2064} 2065``` 2066 2067### commitModify<sup>8+</sup> 2068 2069commitModify(): Promise<void> 2070 2071Commits the modification in the album attributes to the database. This API uses a promise to return the result. 2072 2073**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA 2074 2075**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2076 2077**Return value** 2078 2079| Type | Description | 2080| ------------------- | ------------ | 2081| Promise<void> | Void promise.| 2082 2083**Example** 2084 2085``` 2086async function example() { 2087 let AlbumNoArgsfetchOp = { 2088 selections: '', 2089 selectionArgs: [], 2090 }; 2091 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); 2092 const album = albumList[0]; 2093 album.albumName = 'hello'; 2094 album.commitModify().then(function() { 2095 console.info("commitModify successfully"); 2096 }).catch(function(err){ 2097 console.info("commitModify failed with error:"+ err); 2098 }); 2099} 2100``` 2101 2102### getFileAssets<sup>7+</sup> 2103 2104getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void 2105 2106Obtains the file assets in this album. This API uses an asynchronous callback to return the result. 2107 2108**Required permissions**: ohos.permission.READ_MEDIA 2109 2110**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2111 2112**Parameters** 2113 2114| Name | Type | Mandatory| Description | 2115| -------- | --------------------------------------------------- | ---- | ----------------------------------- | 2116| options | [MediaFetchOptions](#mediafetchoptions7) | Yes | Options for fetching the files. | 2117| callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | Yes | Callback used to return the file assets.| 2118 2119**Example** 2120 2121``` 2122async function example() { 2123 let AlbumNoArgsfetchOp = { 2124 selections: '', 2125 selectionArgs: [], 2126 }; 2127 let fileNoArgsfetchOp = { 2128 selections: '', 2129 selectionArgs: [], 2130 } 2131 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); 2132 const album = albumList[0]; 2133 album.getFileAssets(fileNoArgsfetchOp, getFileAssetsCallBack); 2134 function getFileAssetsCallBack(err, fetchFileResult) { 2135 // do something 2136 } 2137} 2138``` 2139 2140### getFileAssets<sup>7+</sup> 2141 2142 getFileAssets(options?: MediaFetchOptions): Promise<FetchFileResult> 2143 2144Obtains the file assets in this album. This API uses a promise to return the result. 2145 2146**Required permissions**: ohos.permission.READ_MEDIA 2147 2148**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2149 2150**Parameters** 2151 2152| Name | Type | Mandatory| Description | 2153| ------- | ---------------------------------------- | ---- | -------------- | 2154| options | [MediaFetchOptions](#mediafetchoptions7) | No | Options for fetching the files.| 2155 2156**Return value** 2157 2158| Type | Description | 2159| --------------------------------------------- | ------------------------- | 2160| Promise<[FetchFileResult](#fetchfileresult7)> | Promise used to return the file assets.| 2161 2162**Example** 2163 2164``` 2165async function example() { 2166 let AlbumNoArgsfetchOp = { 2167 selections: '', 2168 selectionArgs: [], 2169 }; 2170 let fileNoArgsfetchOp = { 2171 selections: '', 2172 selectionArgs: [], 2173 } 2174 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); 2175 const album = albumList[0]; 2176 album.getFileAssets(fileNoArgsfetchOp).then(function(albumFetchFileResult){ 2177 console.info("getFileAssets successfully:"+ JSON.stringify(albumFetchFileResult)); 2178 }).catch(function(err){ 2179 console.info("getFileAssets failed with error:"+ err); 2180 }); 2181} 2182``` 2183 2184## PeerInfo<sup>8+</sup> 2185 2186Describes information about a registered device. 2187This is a system API. 2188 2189**System capability**: SystemCapability.Multimedia.MediaLibrary.DistributedCore 2190 2191| Name | Type | Readable| Writable| Description | 2192| ---------- | -------------------------- | ---- | ---- | ---------------- | 2193| deviceName | string | Yes | No | Name of the registered device. | 2194| networkId | string | Yes | No | Network ID of the registered device.| 2195| deviceType | [DeviceType](#devicetype8) | Yes | No | Type of the registered device. | 2196| isOnline | boolean | Yes | No | Whether the registered device is online. | 2197 2198 2199 2200## MediaType<sup>8+</sup> 2201 2202Enumerates media types. 2203 2204**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2205 2206| Name | Description| 2207| ----- | ---- | 2208| FILE | File.| 2209| IMAGE | Image.| 2210| VIDEO | Video.| 2211| AUDIO | Audio.| 2212 2213## FileKey<sup>8+</sup> 2214 2215Enumerates key file information. 2216 2217**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2218 2219| Name | Default Value | Description | 2220| ------------- | ------------------- | ---------------------------------------------------------- | 2221| ID | file_id | File ID. | 2222| RELATIVE_PATH | relative_path | Relative public directory of the file. | 2223| DISPLAY_NAME | display_name | Display file name. | 2224| PARENT | parent | Parent directory ID. | 2225| MIME_TYPE | mime_type | Extended file attributes. | 2226| MEDIA_TYPE | media_type | Media type. | 2227| SIZE | size | File size, in bytes. | 2228| DATE_ADDED | date_added | Date when the file was added. (The value is the number of seconds elapsed since the Epoch time.) | 2229| DATE_MODIFIED | date_modified | Date when the file was modified. (The value is the number of seconds elapsed since the Epoch time.) | 2230| DATE_TAKEN | date_taken | Date when the file (photo) was taken. (The value is the number of seconds elapsed since the Epoch time.) | 2231| TITLE | title | Title in the file. | 2232| ARTIST | artist | Artist of the file. | 2233| AUDIOALBUM | audio_album | Audio album. | 2234| DURATION | duration | Duration, in ms. | 2235| WIDTH | width | Image width, in pixels. | 2236| HEIGHT | height | Image height, in pixels. | 2237| ORIENTATION | orientation | Image display direction (clockwise rotation angle, for example, 0, 90, and 180, in degrees).| 2238| ALBUM_ID | bucket_id | ID of the album to which the file belongs. | 2239| ALBUM_NAME | bucket_display_name | Name of the album to which the file belongs. | 2240 2241## DirectoryType<sup>8+</sup> 2242 2243Enumerates directory types. 2244 2245**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2246 2247| Name | Description | 2248| ------------- | ------------------ | 2249| DIR_CAMERA | Directory of camera files.| 2250| DIR_VIDEO | Directory of video files. | 2251| DIR_IMAGE | Directory of image files. | 2252| DIR_AUDIO | Directory of audio files. | 2253| DIR_DOCUMENTS | Directory of documents. | 2254| DIR_DOWNLOAD | Download directory. | 2255 2256## DeviceType<sup>8+</sup> 2257 2258Enumerates device types. 2259This is a system API. 2260 2261**System capability**: SystemCapability.Multimedia.MediaLibrary.DistributedCore 2262 2263| Name | Description | 2264| ------------ | ---------- | 2265| TYPE_UNKNOWN | Unknown.| 2266| TYPE_LAPTOP | Laptop.| 2267| TYPE_PHONE | Phone. | 2268| TYPE_TABLET | Tablet. | 2269| TYPE_WATCH | Smart watch. | 2270| TYPE_CAR | Vehicle-mounted device. | 2271| TYPE_TV | TV. | 2272 2273## MediaFetchOptions<sup>7+</sup> 2274 2275Describes options for fetching media files. 2276 2277**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2278 2279| Name | Type | Readable| Writable| Mandatory| Description | 2280| ----------------------- | ------------------- | ---- | ---- | ---- | ------------------------------------------------------------ | 2281| selections | string | Yes | Yes | Yes | Conditions for fetching files. The enumerated values in [FileKey](#filekey8) are used as the column names of the conditions. Example:<br>selections: mediaLibrary.FileKey.MEDIA_TYPE + '= ? OR ' +mediaLibrary.FileKey.MEDIA_TYPE + '= ?', | 2282| selectionArgs | Array<string> | Yes | Yes | Yes | Value of the condition, which corresponds to the value of the condition column in **selections**.<br>Example:<br>selectionArgs: [mediaLibrary.MediaType.IMAGE.toString(), mediaLibrary.MediaType.VIDEO.toString()], | 2283| order | string | Yes | Yes | No | Sorting mode of the search results, which can be ascending or descending. The enumerated values in [FileKey](#filekey8) are used as the columns for sorting the search results. Example:<br>Ascending: order: mediaLibrary.FileKey.DATE_ADDED + " ASC"<br>Descending: order: mediaLibrary.FileKey.DATE_ADDED + " DESC" | 2284| uri<sup>8+</sup> | string | Yes | Yes | No | File URI. | 2285| networkId<sup>8+</sup> | string | Yes | Yes | No | Network ID of the registered device. | 2286| extendArgs<sup>8+</sup> | string | Yes | Yes | No | Extended parameters for fetching the files. Currently, no extended parameters are available. | 2287 2288## Size<sup>8+</sup> 2289 2290Describes the image size. 2291**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2292 2293| Name | Type | Readable | Writable | Description | 2294| ------ | ------ | ---- | ---- | -------- | 2295| width | number | Yes | Yes | Image width, in pixels.| 2296| height | number | Yes | Yes | Image height, in pixels.| 2297 2298## MediaAssetOption<sup>(deprecated)</sup> 2299 2300Implements the media asset option. 2301 2302> **NOTE** 2303> 2304> This API is deprecated since API version 9. 2305 2306**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2307 2308 2309| Name | Type | Mandatory| Description | 2310| ------------ | ------ | ---- | ------------------------------------------------------------ | 2311| src | string | Yes | Application sandbox oath of the local file. | 2312| mimeType | string | Yes | Multipurpose Internet Mail Extensions (MIME) type of the media.<br>The value can be 'image/\*', 'video/\*', 'audio/\*' or 'file\*'.| 2313| relativePath | string | No | Custom path for storing media assets, for example, 'Pictures/'. If this parameter is unspecified, media assets are stored in the default path.<br> Default path of images: 'Pictures/'<br> Default path of videos: 'Videos/'<br> Default path of audios: 'Audios/'<br> Default path of files: 'Documents/'| 2314 2315## MediaSelectOption<sup>(deprecated)</sup> 2316 2317Describes media selection option. 2318 2319> **NOTE** 2320> 2321> This API is deprecated since API version 9. 2322 2323**System capability**: SystemCapability.Multimedia.MediaLibrary.Core 2324 2325| Name | Type | Mandatory | Description | 2326| ----- | ------ | ---- | -------------------- | 2327| type | string | Yes | Media type, which can be **image**, **media**, or **video**. Currently, only **media** is supported.| 2328| count | number | Yes | Number of media assets selected. The value starts from 1, which indicates that one media asset can be selected. | 2329
