diff --git a/en/application-dev/Readme-EN.md b/en/application-dev/Readme-EN.md index f3fa0e7ac0e9b829f2418e4b1bf96001e66553d2..ca2c2fda1462b991f8ea60f36b5c181783034874 100644 --- a/en/application-dev/Readme-EN.md +++ b/en/application-dev/Readme-EN.md @@ -16,6 +16,7 @@ - [Application Package Structure Configuration File (Stage Model)](quick-start/stage-structure.md) - [SysCap](quick-start/syscap.md) - [HarmonyAppProvision Configuration File](quick-start/app-provision-structure.md) + - Development - [Ability Development](ability/Readme-EN.md) - [UI Development](ui/Readme-EN.md) @@ -26,6 +27,7 @@ - [Security](security/Readme-EN.md) - [Connectivity](connectivity/Readme-EN.md) - [Data Management](database/Readme-EN.md) + - [File Management](file-management/Readme-EN.md) - [Telephony](telephony/Readme-EN.md) - [Task Management](task-management/Readme-EN.md) - [Device Management](device/Readme-EN.md) diff --git a/en/application-dev/file-management/Readme-EN.md b/en/application-dev/file-management/Readme-EN.md new file mode 100644 index 0000000000000000000000000000000000000000..4bb5fe54817e245807612eaac1a0b6d235101f7a --- /dev/null +++ b/en/application-dev/file-management/Readme-EN.md @@ -0,0 +1,6 @@ +# File Management +- MediaLibrary Management + - [MediaLibrary Overview](medialibrary-overview.md) + - [Media Asset Management](medialibrary-resource-guidelines.md) + - [File Path Management](medialibrary-filepath-guidelines.md) + - [Album Management](medialibrary-album-guidelines.md) \ No newline at end of file diff --git a/en/application-dev/file-management/medialibrary-album-guidelines.md b/en/application-dev/file-management/medialibrary-album-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..322e596ef6a0776291ab36529fb10760c09b4c51 --- /dev/null +++ b/en/application-dev/file-management/medialibrary-album-guidelines.md @@ -0,0 +1,94 @@ +# Album Management + +You can use the APIs provided by the **mediaLibrary** module to create and delete an album and obtain images in the album. + +> **NOTE** +> +> Before developing features, read [MediaLibrary Overview](medialibrary-overview.md) to learn how to obtain a **MediaLibrary** instance and request the permissions to call the APIs of **MediaLibrary**. + +To ensure the application running efficiency, most **MediaLibrary** API calls are asynchronous, and both callback and promise modes are provided for these APIs. The following code samples use the promise mode. For details about the APIs, see [MediaLibrary API Reference](../reference/apis/js-apis-medialibrary.md). + +## Obtaining Images and Videos in an Album + +You can obtain images and videos in an album in either of the following ways: + +- Call [MediaLibrary.getFileAssets](../reference/apis/js-apis-medialibrary.md#getfileassets7-1) with an album specified to obtain the media assets. For details, see [Querying Media Assets with the Specified Album Name](medialibrary-resource-guidelines#querying-media-assets-with-the-specified-album-name). + +- Call [Album.getFileAssets](../reference/apis/js-apis-medialibrary.md#getfileassets7-3) to obtain an **Album** instance, so as to obtain the media assets in it. For details, see [Obtaining Images and Videos in an Album](medialibrary-resource-guidelines#obtaining-images-and-videos-in-an-album). + +## Creating an Album + +You can use [MediaLibrary.createAsset](../reference/apis/js-apis-medialibrary.md#createasset8-1), with the relative path set, to create an album while adding a media asset to the album. The relative path is the album name. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. + +The following describes how to create an album named **myAlbum**. + +**How to Develop** + +1. Call **getPublicDirectory** to obtain the public directory that stores files of a certain type. + + For details about the operation, see [Obtaining a Public Directory](medialibrary-filepath-guidelines.md#obtaining-a-public-directory). + +2. Call **createAsset** to create an image, with the relative path set to **path + 'myAlbum/'**. + + This operation creates an album and adds an image to it. + +```ts +async function example() { + let mediaType = mediaLibrary.MediaType.IMAGE; + let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const path = await media.getPublicDirectory(DIR_IMAGE) + // myAlbum is the path for storing the new file and the name of the new album. + media.createAsset(mediaType, 'test.jpg', path + 'myAlbum/', (err, fileAsset) => { + if (fileAsset != undefined) { + console.info('createAlbum successfully, message = ' + fileAsset); + } else { + console.info('createAlbum failed, message = ' + err); + } + }); +} +``` + +## Renaming an Album + +Renaming modifies the **FileAsset.albumName** attribute of the album, that is, the album name. After the modification, call [Album.commitModify](../reference/apis/js-apis-medialibrary.md#commitmodify8-3) to commit the modification to the database. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. + +The following describes how to rename the album **newAlbum**. + +**How to Develop** + +1. Create a retrieval condition for obtaining the target album. +2. Call **getAlbums** to obtain the album list. +3. Rename the album **newAlbum**. +4. Call **Album.commitModify** to commit the modification of the attributes to the database. + +```ts +async function example() { + let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let albumList = await media.getAlbums(AlbumNoArgsfetchOp); + let album = albumList[0]; + album.albumName = 'newAlbum'; + // Void callback. + album.commitModify().then(function() { + console.info("albumRename successfully"); + }).catch(function(err){ + console.info("albumRename failed with error:"+ err); + }); +} +``` diff --git a/en/application-dev/file-management/medialibrary-filepath-guidelines.md b/en/application-dev/file-management/medialibrary-filepath-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..fc9b327031cfee8ea6de601b3c3d268bbf161c53 --- /dev/null +++ b/en/application-dev/file-management/medialibrary-filepath-guidelines.md @@ -0,0 +1,244 @@ +# File Path Management + +User data on OpenHarmony is managed by the **mediaLibrary** module in a unified manner. You can use the APIs provided by this module to access and operate the user data. + +> **NOTE** +> +> Before developing features, read [MediaLibrary Overview](medialibrary-overview.md) to learn how to obtain a **MediaLibrary** instance and request the permissions to call the APIs of **MediaLibrary**. + +To ensure the application running efficiency, most **MediaLibrary** API calls are asynchronous, and both callback and promise modes are provided for these APIs. The following code samples use the promise mode. For details about the APIs, see [MediaLibrary API Reference](../reference/apis/js-apis-medialibrary.md). + +## File Formats Supported by Public Directories + +Before using file paths for development, learn the file formats supported by each public directory. +> **CAUTION** +> +> The following table lists only the file types that can be identified by the system. In your application development, pay attention to the file formats supported by the corresponding interfaces.
For example, only .jpeg and .webp can be used for image encoding, and only .jpg, .png, .gif, .bmp, .webp, and .raw can be used for image decoding. + +| Directory | Directory Type | Media Type | Description | Supported File Format | +| ---------- | ------------- | ------------- | -------------- | ------------------------------------------------------------ | +| Camera/ | DIR_CAMERA | VIDEO and IMAGE | Directory for storing images and videos taken by the camera. Videos and images can be stored in this directory and its subdirectories.| .bmp / .bm / .gif / .jpg /. jpeg / .jpe / .png / .webp / .raw / .svg / .heif / .mp4 / .3gp / .mpg / .mov / .webm / .mkv | +| Videos/ | DIR_VIDEO | VIDEO | Dedicated video directory. Only videos can be stored in this directory and its subdirectories.| .mp4 / .3gp / .mpg / .mov / .webm / .mkv | +| Pictures/ | DIR_IMAGE | IMAGE | Dedicated image directory. Only images can be stored in this directory and its subdirectories.| .bmp / .bm / .gif / .jpg /. jpeg / .jpe / .png / .webp / .raw / .svg / .heif | +| Audios/ | DIR_AUDIO | AUDIO |Dedicated audio directory. Only audio files can be stored in this directory and its subdirectories.| .aac/.mp3/.flac/.wav/.ogg | +| Documents/ | DIR_DOCUMENTS | FILE |Dedicated file directory. Only files except audios, images, and videos can be stored in this directory and its subdirectories.| - | +| Download/ | DIR_DOWNLOAD | ALLTYPE |Directory for storing downloaded files. The types of files in this directory and its subdirectories are not restricted.| - | + +## Obtaining a Public Directory + +Different types of files are stored in different public directories. You can call [getPublicDirectory](../reference/apis/js-apis-medialibrary.md#getpublicdirectory8-1) to obtain the public directory that stores files of a certain type. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.READ_MEDIA**. + +The following describes how to obtain the public directory that stores camera files. + +```ts +async function example(){ + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; + const dicResult = await media.getPublicDirectory(DIR_CAMERA); + if (dicResult == 'Camera/') { + console.info('mediaLibraryTest : getPublicDirectory passed'); + } else { + console.info('mediaLibraryTest : getPublicDirectory failed'); + } +} +``` + +## Copying Files Between the Application Sandbox and the Public Directory + +OpenHarmony provides the application sandbox to minimize the leakage of application data and user privacy information. + +Users can access files stored in the public directories through the system applications **Files** and **Gallery**. However, files in the application sandbox can be accessed only by the application itself. + +### Copying a File + +You can call [mediaLibrary.FileAsset.open](../reference/apis/js-apis-medialibrary.md#open8-1) to open a file in a public directory. + +You can call [fileio.open](../reference/apis/js-apis-fileio.md#fileioopen7) to open a file in the application sandbox. The sandbox directory can be accessed only through the application context. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. +- You have imported the module [@ohos.fileio](../reference/apis/js-apis-fileio.md) in addition to @ohos.multimedia.mediaLibrary. + +**How to Develop** + +1. Call [Context.getFilesDir](../reference/apis/js-apis-Context.md#contextgetfilesdir) to obtain the directory of the application sandbox. +2. Call **MediaLibrary.getFileAssets** and **FetchFileResult.getFirstObject** to obtain the first file in the result set of the public directory. +3. Call **fileio.open** to open the file in the sandbox. +4. Call **fileAsset.open** to open the file in the public directory. +5. Call **fileio.copyfile** to copy the file. +6. Call **fileAsset.close** and **fileio.close** to close the file. + +**Example 1: Copying Files from the Public Directory to the Sandbox** + +```ts +async function copyPublic2Sandbox() { + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let sandboxDirPath = globalThis.context.filesDir; + let fileKeyObj = mediaLibrary.FileKey + let fileAssetFetchOp = { + selections: fileKeyObj.DISPLAY_NAME + '= ?' , + selectionArgs: ['testFile.txt'], + }; + let fetchResult = await media.getFileAssets(fileAssetFetchOp); + let fileAsset = await fetchResult.getFirstObject(); + + let fdPub = await fileAsset.open('rw'); + let fdSand = await fileio.open(sandboxDirPath + '/testFile.txt', 0o2 | 0o100, 0o666); + await fileio.copyFile(fdPub, fdSand); + + await fileAsset.close(fdPub); + await fileio.close(fdSand); + + let content_sand = await fileio.readText(sandboxDirPath + '/testFile.txt'); + console.log('content read from sandbox file: ', content_sand) +} +``` + +**Example 2: Copying a File from the Sandbox to the Public Directory** + +```ts +async function copySandbox2Public() { + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let sandboxDirPath = globalThis.context.filesDir; + + let DIR_DOCUMENTS = mediaLibrary.DirectoryType.DIR_DOCUMENTS; + const publicDirPath = await media.getPublicDirectory(DIR_DOCUMENTS); + try { + let fileAsset = await media.createAsset(mediaLibrary.MediaType.FILE, 'testFile02.txt', publicDirPath); + console.info('createFile successfully, message = ' + fileAsset); + } catch (err) { + console.info('createFile failed, message = ' + err); + } + try { + let fileKeyObj = mediaLibrary.FileKey + let fileAssetFetchOp = { + selections: fileKeyObj.DISPLAY_NAME + '= ?' , + selectionArgs: ['testFile02.txt'], + }; + let fetchResult = await media.getFileAssets(fileAssetFetchOp); + var fileAsset = await fetchResult.getFirstObject(); + } catch (err) { + console.info('file asset get failed, message = ', err) + } + var fdPub = await fileAsset.open('rw'); + var fdSand = await fileio.open(sandboxDirPath + 'testFile.txt', 0o2); + await fileio.copyFile(fdSand, fdPub); + await fileio.close(fdPub); + await fileio.close(fdSand); + let fdPubRead = await fileAsset.open('rw'); + try { + var arrayBuffer = new ArrayBuffer(4096); + await fileio.read(fdPubRead, arrayBuffer); + var content_pub = String.fromCharCode(new Uint8Array(arrayBuffer)); + fileAsset.close(fdPubRead); + } catch (err) { + console.log('read text failed, message = ', err); + } + console.log('content read from public file: ', content_pub); +} +``` + +### Reading and Writing a File + +You can use **FileAsset.open** and **FileAsset.close** of [mediaLibrary](../reference/apis/js-apis-medialibrary.md) to open and close a file, and use **fileio.read** and **fileio.write** of [fileio](../reference/apis/js-apis-fileio.md) to read and write a file. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. +- You have imported the module [@ohos.fileio](../reference/apis/js-apis-fileio.md) in addition to @ohos.multimedia.mediaLibrary. + +**How to Develop** + +1. Create a file. + + ```ts + async function example() { + let mediaType = mediaLibrary.MediaType.FILE; + let DIR_DOCUMENTS = mediaLibrary.DirectoryType.DIR_DOCUMENTS; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const path = await media.getPublicDirectory(DIR_DOCUMENTS); + media.createAsset(mediaType, "testFile.text", path).then (function (asset) { + console.info("createAsset successfully:"+ JSON.stringify(asset)); + }).catch(function(err){ + console.info("createAsset failed with error:"+ err); + }); + } + ``` + +2. Call **FileAsset.open** to open the file. + +3. Call **fileio.write** to write a string to the file. + +4. Call **fileio.read** to read the file and save the data read in an array buffer. + +5. Convert the array buffer to a string. + +6. Use **FileAsset.close** to close the file. + +**Example 1: Opening an Existing File and Writing Data to It** + +```ts +async function writeOnlyPromise() { + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey + let fileAssetFetchOp = { + selections: fileKeyObj.DISPLAY_NAME + '= ?' , + selectionArgs: ['testFile.txt'], + }; + let fetchResult = await media.getFileAssets(fileAssetFetchOp); + let fileAsset = await fetchResult.getFirstObject(); + console.info('fileAssetName: ', fileAsset.displayName); + + try { + let fd = await fileAsset.open('w'); + console.info('file descriptor: ', fd); + await fileio.write(fd, "Write file test content."); + await fileAsset.close(fd); + } catch (err) { + console.info('write file failed, message = ', err); + } +} +``` + +**Example 2: Opening an Existing File and Reading Data from It** + +```ts +async function readOnlyPromise() { + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey + let fileAssetFetchOp = { + selections: fileKeyObj.DISPLAY_NAME + '= ?' , + selectionArgs: ['testFile.txt'], + }; + let fetchResult = await media.getFileAssets(fileAssetFetchOp); + let fileAsset = await fetchResult.getFirstObject(); + console.info('fileAssetName: ', fileAsset.displayName); + + try { + let fd = await fileAsset.open('r'); + let arrayBuffer = new ArrayBuffer(4096); + await fileio.read(fd, arrayBuffer); + let fileContent = String.fromCharCode(...new Uint8Array(arrayBuffer)); + globalThis.fileContent = fileContent + globalThis.fileName = fileAsset.displayName; + console.info('file content: ', fileContent); + await fileAsset.close(fd); + } catch (err) { + console.info('read file failed, message = ', err); + } +} +``` diff --git a/en/application-dev/file-management/medialibrary-overview.md b/en/application-dev/file-management/medialibrary-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..79f13fe066967607ab15f096fe3ce5478aaa9abe --- /dev/null +++ b/en/application-dev/file-management/medialibrary-overview.md @@ -0,0 +1,127 @@ +# MediaLibrary Development Overview + +The **mediaLibrary** module provides APIs for you to access and modify media files. + +- You can manage [media assets (audios, videos, image, and files)](medialibrary-resource-guidelines.md) as follows: + - Query media assets. + - Obtain an image or a video. + - Obtain the thumbnail of an image or a video. + - Create a media asset. + - Rename a media asset. + - Move a media asset to the recycle bin. +- You can manage [file paths](medialibrary-filepath-guidelines.md) as follows: + - Obtain the public directory that stores files of a certain type. + - Copy files between the application sandbox and the public directory. + - Read and write a file. +- You can manage [albums](medialibrary-album-guidelines.md) as follows: + - Obtain images and videos in an album. + - Create an album. + - Rename an album. + +> **NOTE** +> +> This development guide applies only to the stage model (available from API version 9). + +To access and modify personal media data, an application must obtain a **MediaLibrary** instance and request the media asset read and write permissions from the user. + +Before using the **MediaLibrary** APIs to develop features, you must learn how to: + +- [Obtain a MediaLibrary Instance](#obtaining-a-medialibrary-instance) +- [Request Permissions](#requesting-permissions) + +## Obtaining a MediaLibrary Instance + +An application must call [getMediaLibrary](../reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary8) to obtain a **MediaLibrary** instance based on the application context. Through this instance, the application can access and modify personal media data (such as audios, videos, images, and files). + +**How to Develop** + +1. Import the **mediaLibrary** module. +2. Call **getContext** to obtain the application context. +3. Obtain a **MediaLibrary** instance. + +```ts +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +const context = getContext(this); +var media = mediaLibrary.getMediaLibrary(context); +``` + +## Requesting Permissions + +To read and write a **MediaLibrary** instance, you must have the required permissions, as described in the table below. Before requesting the permissions, ensure that the [basic principles for permission management](../security/accesstoken-overview.md#basic-principles-for-permission-management) are met. + +| Permission | Description | Authorization Mode | +| ------------------------------ | ------------------------------------------ | ---------- | +| ohos.permission.READ_MEDIA | Allows an application to read media files from the user's external storage.| user_grant | +| ohos.permission.WRITE_MEDIA | Allows an application to read media files from and write media files into the user's external storage.| user_grant | +| ohos.permission.MEDIA_LOCATION | Allows an application to access geographical locations in the user's media file.| user_grant | + +After configuring the permissions in the **module.json5** file, the application must call [Context.requestPermissionsFromUser](../reference/apis/js-apis-ability-context.md#abilitycontextrequestpermissionsfromuser) to check for the required permissions and if they are not granted, request the permissions from the user by displaying a dialog box. + +> **NOTE**
Even if the user has granted a permission, the application must check for the permission before calling an API protected by the permission. It should not persist the permission granted status, because the user can revoke the permission through the system application **Settings**. + +**How to Develop** + +1. Declare the permissions in the **module.json5** file. Add the **requestPermissions** tag under **module** in the file, and set the tag based on the project requirements. For details about the tag, see [Guide for Requesting Permissions from User](../security/accesstoken-guidelines.md). + + ```json + { + "module": { + "requestPermissions": [ + { + "name": "ohos.permission.MEDIA_LOCATION", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "MainAbility" + ], + "when": "always" + } + }, + { + "name": "ohos.permission.READ_MEDIA", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "MainAbility" + ], + "when": "always" + } + }, + { + "name": "ohos.permission.WRITE_MEDIA", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "MainAbility" + ], + "when": "always" + } + } + ] + } + } + ``` + +2. Call **requestPermissionsFromUser** to check for the required permissions and if they are not granted, request the permissions from the user by displaying a dialog box. + + ```ts + import Ability from '@ohos.application.Ability' + + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + var permissions=['ohos.permission.READ_MEDIA','ohos.permission.WRITE_MEDIA'] + var permissionRequestResult; + this.context.requestPermissionsFromUser(permissions,(err,result) => { + if(err){ + console.log('requestPermissionsFromUserError: ' + JSON.stringify(err)); + }else{ + permissionRequestResult=result; + console.log('permissionRequestResult: ' + JSON.stringify(permissionRequestResult)); + } + }); + } + } + ``` + + diff --git a/en/application-dev/file-management/medialibrary-resource-guidelines.md b/en/application-dev/file-management/medialibrary-resource-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..737ea4e48fa24c38f47fe7595e9df6e1370ab69a --- /dev/null +++ b/en/application-dev/file-management/medialibrary-resource-guidelines.md @@ -0,0 +1,389 @@ +# Media Asset Management + +Your applications can use the APIs provided by the **mediaLibrary** module to perform operations on media assets such as audios, videos, images, and files. + +> **NOTE** +> +> Before developing features, read [MediaLibrary Overview](medialibrary-overview.md) to learn how to obtain a **MediaLibrary** instance and request the permissions to call the APIs of **MediaLibrary**. + +To ensure the application running efficiency, most **MediaLibrary** API calls are asynchronous, and both callback and promise modes are provided for these APIs. The following code samples use the promise mode. For details about the APIs, see [MediaLibrary API Reference](../reference/apis/js-apis-medialibrary.md). + +## Querying Media Assets + +You can query media assets by condition such as the media type, date, or album name. + +To do so, call [MediaLibrary.getFileAssets](../reference/apis/js-apis-medialibrary.md#getfileassets7-1), with a **MediaFetchOptions** object passed in to specify the conditions. In this object, **MediaFetchOptions.selections** are the retrieval conditions, and the enumerated values of **FileKey** are used as the column names of the conditions; **MediaFetchOptions.selectionArgs** are the values of the conditions. You can also specify **order** (sorting mode of the search result), **uri** (file URI), and **networkId** (network ID of the registered device) as the conditions. + +To obtain the object at the specified position (for example, the first, the last, or with the specified index) in the result set, call [FetchFileResult](../reference/apis/js-apis-medialibrary.md#fetchfileresult7). In this section, **getNextObject** is used cyclically to obtain all media assets in the result set. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.READ_MEDIA**. + +### Querying Media Assets with the Specified Media Type + +The following describes how to obtain images. + +**How to Develop** + +To specify the media type as the retrieval condition, set **selections** to **FileKey.MEDIA_TYPE**. + +To specify the image as the media type, set **selectionArgs** to **MediaType.IMAGE**. + +```ts +async function example() { + let fileKeyObj = mediaLibrary.FileKey + let fileType = mediaLibrary.MediaType.IMAGE + let option = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [fileType.toString()], + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const fetchFileResult = await media.getFileAssets(option); + for (let i = 0; i < fetchFileResult.getCount(); i++) { + fetchFileResult.getNextObject((err, fileAsset) => { + if (err) { + console.error('Failed '); + return; + } + console.log('fileAsset.displayName ' + i + ': ' + fileAsset.displayName); + }) + } +} +``` + +### Querying Media Assets with the Specified Date + +The following describes how to obtain media assets that are added on the specified date. You can also use the modification date and shooting date as the retrieval conditions. + +To specify the date when the files are added as the retrieval condition, set **selections** to **FileKey.DATE_ADDED**. + +To specify the date 2022-8-5, set **selectionArgs** to **2022-8-5**. + +```ts +async function example() { + let fileKeyObj = mediaLibrary.FileKey + let option = { + selections: fileKeyObj.DATE_ADDED + '= ?', + selectionArgs: ['2022-8-5'], + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const fetchFileResult = await media.getFileAssets(option); + for (let i = 0; i < fetchFileResult.getCount(); i++) { + fetchFileResult.getNextObject((err, fileAsset) => { + if (err) { + console.error('Failed '); + return; + } + console.log('fileAsset.displayName ' + i + ': ' + fileAsset.displayName); + }) + } +} +``` + +### Querying Media Assets and Sorting Them + +The following describes how to query images and sort them in descending order by the date when they are added. You can also sort them in ascending order. + +To sort files in descending order by the date when they are added, set **order** to **FileKey.DATE_ADDED + " DESC"**. + +```ts +async function example() { + let fileKeyObj = mediaLibrary.FileKey + let fileType = mediaLibrary.MediaType.IMAGE + let option = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [fileType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const fetchFileResult = await media.getFileAssets(option); + for (let i = 0; i < fetchFileResult.getCount(); i++) { + fetchFileResult.getNextObject((err, fileAsset) => { + if (err) { + console.error('Failed '); + return; + } + console.log('fileAsset.displayName ' + i + ': ' + fileAsset.displayName); + }) + } +} +``` + +### Querying Media Assets with the Specified Album Name + +The following describes how to query media assets in **myAlbum**. + +To specify the album name as the retrieval condition, set **selections** to **FileKey.ALBUM_NAME**. + +To specify the album name **'myAlbum'**, set **selectionArgs** to **'myAlbum'**. + +```ts +async function example() { + let fileKeyObj = mediaLibrary.FileKey + let fileType = mediaLibrary.MediaType.IMAGE + let option = { + selections: fileKeyObj.ALBUM_NAME + '= ?', + selectionArgs: ['myAlbum'], + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const fetchFileResult = await media.getFileAssets(option); + for (let i = 0; i < fetchFileResult.getCount(); i++) { + fetchFileResult.getNextObject((err, fileAsset) => { + if (err) { + console.error('Failed '); + return; + } + console.log('fileAsset.displayName ' + i + ': ' + fileAsset.displayName); + }) + } +} +``` + +## Obtaining Images and Videos in an Album + +You can obtain media assets in an album in either of the following ways: + +- Call [MediaLibrary.getFileAssets](../reference/apis/js-apis-medialibrary.md#getfileassets7-1) with an album specified, as described in [Querying Media Assets with the Specfied Album Name](#querying-media-assets-with-the-specified-album-name). +- Call [Album.getFileAssets](../reference/apis/js-apis-medialibrary.md#getfileassets7-3) to obtain an **Album** instance, so as to obtain the media assets in it. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.READ_MEDIA**. + +**How to Develop** + +The following describes how to obtain videos in an album named **New Album 1**. + +1. Create a retrieval condition for obtaining the target **Album** instance. + + ```ts + let fileKeyObj = mediaLibrary.FileKey; + let AlbumNoArgsFetchOp = { + selections: fileKeyObj.ALBUM_NAME + '= ?', + selectionArgs:['New Album 1'] + } + ``` + +2. Create a retrieval condition for obtaining videos in the target album. + + ```ts + let fileKeyObj = mediaLibrary.FileKey; + let imageType = mediaLibrary.MediaType.VIDEO; + let imagesFetchOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + } + ``` + +3. Call **Album.getFileAssets** to obtain the videos in the target album. + +Complete sample code: + +```ts +async function getCameraImagePromise() { + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey; + let imageType = mediaLibrary.MediaType.IMAGE; + let imagesFetchOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + } + let AlbumNoArgsFetchOp = { + selections: fileKeyObj.ALBUM_NAME + '= ?', + selectionArgs:['New Album 1'] + } + + let albumList = await media.getAlbums(AlbumNoArgsFetchOp); + if (albumList.length > 0) { + const album = albumList[0]; + let fetchFileResult = await album.getFileAssets(imagesFetchOp); + let count = fetchFileResult.getCount(); + console.info("get mediaLibrary IMAGE number", count); + } else { + console.info('getAlbum list is: 0'); + } +} +``` + +## Obtaining the Thumbnail of an Image or a Video + +You can call [FileAsset.getThumbnail](../reference/apis/js-apis-medialibrary.md#getthumbnail8-2) with the thumbnail size passed in to obtain the thumbnail of an image or a video. Thumbnails are usually displayed on the UI. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.READ_MEDIA**. + +### Obtaining the Thumbnail of an Image + +Your application may need to obtain the thumbnail of an image for preview purposes. + +The following describes how to obtain the thumbnail (size: 720 x 720) of the first image in the album. + +**How to Develop** + +1. Create a retrieval condition for obtaining images in the target album. +2. Call **getFileAssets** to obtain the images in the target album. +3. Call **getFirstObject** to obtain the first image among all the images obtained. +4. Call **getThumbnail** to obtain the thumbnail of the first image. + +```ts +async function getFirstThumbnailPromise() { + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey; + let imageType = mediaLibrary.MediaType.IMAGE; + let imagesFetchOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + } + + let size = { width: 720, height: 720 }; + const fetchFileResult = await media.getFileAssets(imagesFetchOp); + if (fetchFileResult != undefined) { + const asset = await fetchFileResult.getFirstObject(); + asset.getThumbnail(size).then((pixelMap) => { + pixelMap.getImageInfo().then((info) => { + console.info('get Thumbnail info: ' + "width: " + info.size.width + " height: " + info.size.height); + }).catch((err) => { + console.info("getImageInfo failed with error:" + err); + }); + }).catch((err) => { + console.info("getImageInfo failed with error:" + err); + }); + } else { + console.info("get image failed with error"); + } +} +``` + +## Creating a Media Asset + +You can call [MediaLibrary.createAsset](../reference/apis/js-apis-medialibrary.md#createasset8-1) to create a media asset. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. +- [Obtain the public directory](medialibrary-filepath-guidelines.md). + +The following describes how to create a file of the **MediaType.FILE** type. + +```ts +async function example() { + let mediaType = mediaLibrary.MediaType.FILE; + let DIR_DOCUMENTS = mediaLibrary.DirectoryType.DIR_DOCUMENTS; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const path = await media.getPublicDirectory(DIR_DOCUMENTS); + media.createAsset(mediaType, "testFile.text", path).then ((asset) => { + console.info("createAsset successfully:"+ JSON.stringify(asset)); + }).catch((err) => { + console.info("createAsset failed with error:"+ err); + }); +} +``` + +## Moving a Media Asset to the Recycle Bin + +You can use [FileAsset.trash](../reference/apis/js-apis-medialibrary.md#trash8) to move a media asset to the recycle bin. + +By default, files in the recycle bin will be stored for 30 days. During this period, you can set **isTrash** in **trash** to **false** to recover the files from the recycle bin. Application users can also recover the files through the system applications **Files** or **Gallery**. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. + +The following describes how to move the first file in the result set to the recycle bin. + +**How to Develop** + +1. Create a retrieval condition for obtaining images in the target album. +2. Call **getFileAssets** to obtain the images in the target album. +3. Call **getFirstObject** to obtain the first image among all the images obtained. +4. Call **trash** to move the first image to the recycle bin. + +```ts +async function example() { + let fileKeyObj = mediaLibrary.FileKey + let fileType = mediaLibrary.MediaType.FILE + let option = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [fileType.toString()], + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const fetchFileResult = await media.getFileAssets(option); + let asset = await fetchFileResult.getFirstObject(); + if (asset == undefined) { + console.error('asset not exist') + return + } + // Void callback. + asset.trash(true).then(() => { + console.info("trash successfully"); + }).catch((err) => { + console.info("trash failed with error:"+ err); + }); +} +``` + +## Renaming a Media Asset + +Renaming modifies the **FileAsset.displayName** attribute of a file, that is, the displayed file name, including the file name extension. + +After the modification, call [FileAsset.commitModify](../reference/apis/js-apis-medialibrary.md#commitmodify8-1) to commit the modification to the database. + +Before renaming a file, you must call [FetchFileResult](../reference/apis/js-apis-medialibrary.md#fetchfileresult7) to obtain the file. + +**Prerequisites** + +- You have obtained a **MediaLibrary** instance. +- You have granted the permission **ohos.permission.WRITE_MEDIA**. + +The following describes how to rename the first file in the result set as **newtitle.text**. + +**How to Develop** + +1. Create a retrieval condition for obtaining images in the target album. +2. Call **getFileAssets** to obtain the images in the target album. +3. Call **getFirstObject** to obtain the first image among all the images obtained. +4. Rename the image as **newImage.jpg**. +5. Call **FileAsset.commitModify** to commit the modification of the attributes to the database. + +```ts +async function example() { + let fileKeyObj = mediaLibrary.FileKey + let fileType = mediaLibrary.MediaType.FILE + let option = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [fileType.toString()], + }; + const context = getContext(this); + var media = mediaLibrary.getMediaLibrary(context); + const fetchFileResult = await media.getFileAssets(option); + let asset = await fetchFileResult.getFirstObject(); + if (asset == undefined) { + console.error('asset not exist') + return + } + asset.displayName = 'newImage.jpg'; + // Void callback. + asset.commitModify((err) => { + if (err) { + console.error('fileRename Failed '); + return; + } + console.log('fileRename successful.'); + }) +} +```