# @ohos.multimedia.medialibrary (媒体库管理) > **说明：** > > - 该组件从API Version 6开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 > - 从API Version 9开始废弃。保留至API Version 13版本。 > - 部分功能变更为系统接口，仅供系统应用使用，请使用[@ohos.filemanagement.userFileManager](js-apis-userFileManager.md)相应接口替代。 > - 媒体资源选择和保存功能仍开放给普通应用，请使用[@ohos.file.picker](js-apis-file-picker.md)相应接口替代。 ## 导入模块 ```js import mediaLibrary from '@ohos.multimedia.mediaLibrary'; ``` ## mediaLibrary.getMediaLibrary8+ getMediaLibrary(context: Context): MediaLibrary 获取媒体库的实例，用于访问和修改用户等个人媒体数据信息（如音频、视频、图片、文档等）。 此接口仅可在Stage模型下使用。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | -------------------------- | | context | Context | 是 | 传入Ability实例的Context。 | **返回值：** | 类型 | 说明 | | ----------------------------- | :---- | | [MediaLibrary](#medialibrary) | 媒体库实例。 | **示例：（从API Version 9开始）** ```ts // 获取mediaLibrary实例，后续用到此实例均采用此处获取的实例。 const context = getContext(this); let media = mediaLibrary.getMediaLibrary(context); ``` **示例：（API Version 8）** ```js import featureAbility from '@ohos.ability.featureAbility'; let context = featureAbility.getContext(); let media = mediaLibrary.getMediaLibrary(context); ``` ## mediaLibrary.getMediaLibrary getMediaLibrary(): MediaLibrary 获取媒体库的实例，用于访问和修改用户等个人媒体数据信息（如音频、视频、图片、文档等）。 此接口仅可在FA模型下使用。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ----------------------------- | :--------- | | [MediaLibrary](#medialibrary) | 媒体库实例。 | **示例：** ```js let media = mediaLibrary.getMediaLibrary(); ``` ## MediaLibrary ### getFileAssets7+ getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void 获取文件资源，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------------------------------- | ---- | --------------------------------- | | options | [MediaFetchOptions](#mediafetchoptions7) | 是 | 文件检索选项。 | | callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | 是 | callback返回文件检索结果集。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; // 创建文件获取选项，此处参数为获取image类型的文件资源。 let imagesFetchOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], }; // 获取文件资源，使用callback方式返回异步结果。 media.getFileAssets(imagesFetchOp, async (error, fetchFileResult) => { // 判断获取的文件资源的检索结果集是否为undefined，若为undefined则接口调用失败。 if (fetchFileResult == undefined) { console.error('get fetchFileResult failed with error: ' + error); return; } // 获取文件检索结果集中的总数。 const count = fetchFileResult.getCount(); // 判断结果集中的数量是否小于0，小于0时表示接口调用失败。 if (count < 0) { console.error('get count from fetchFileResult failed, count: ' + count); return; } // 判断结果集中的数量是否等于0，等于0时表示接口调用成功，但是检索结果集为空，请检查文件获取选项参数配置是否有误和设备中是否存在相应文件。 if (count == 0) { console.info('The count of fetchFileResult is zero'); return; } console.info('Get fetchFileResult successfully, count: ' + count); // 获取文件检索结果集中的第一个资源，使用callback方式返回异步结果，文件数量较多时请使用getAllObject接口。 fetchFileResult.getFirstObject(async (error, fileAsset) => { // 检查获取的第一个资源是否为undefined，若为undefined则接口调用失败。 if (fileAsset == undefined) { console.error('get first object failed with error: ' + error); return; } console.info('fileAsset.displayName ' + '0 : ' + fileAsset.displayName); // 调用 getNextObject 接口获取下一个资源，直到最后一个。 for (let i = 1; i < count; i++) { let fileAsset = await fetchFileResult.getNextObject(); console.info('fileAsset.displayName ' + i + ': ' + fileAsset.displayName); } // 释放FetchFileResult实例并使其失效。无法调用其他方法。 fetchFileResult.close(); }); }); } ``` ### getFileAssets7+ getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> 获取文件资源，使用Promise方式返回结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------------ | | options | [MediaFetchOptions](#mediafetchoptions7) | 是 | 文件检索选项。 | **返回值：** | 类型 | 说明 | | ------------------------------------ | -------------- | | Promise<[FetchFileResult](#fetchfileresult7)> | Promise对象，返回文件检索结果集。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; // 创建文件获取选项，此处参数为获取image类型的文件资源。 let imagesFetchOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], }; // 获取文件资源，使用Promise方式返回结果。 media.getFileAssets(imagesFetchOp).then(async (fetchFileResult) => { // 获取文件检索结果集中的总数。 const count = fetchFileResult.getCount(); // 判断结果集中的数量是否小于0，小于0时表示接口调用失败。 if (count < 0) { console.error('get count from fetchFileResult failed, count: ' + count); return; } // 判断结果集中的数量是否等于0，等于0时表示接口调用成功，但是检索结果集为空，请检查文件获取选项参数配置是否有误和设备中是否存在相应文件。 if (count == 0) { console.info('The count of fetchFileResult is zero'); return; } console.info('Get fetchFileResult successfully, count: ' + count); // 获取文件检索结果集中的第一个资源，使用Promise方式返回异步结果，文件数量较多时请使用getAllObject接口。 fetchFileResult.getFirstObject().then(async (fileAsset) => { console.info('fileAsset.displayName ' + '0 : ' + fileAsset.displayName); // 调用 getNextObject 接口获取下一个资源，直到最后一个。 for (let i = 1; i < count; i++) { let fileAsset = await fetchFileResult.getNextObject(); console.info('fileAsset.displayName ' + i + ': ' + fileAsset.displayName); } // 释放FetchFileResult实例并使其失效。无法调用其他方法。 fetchFileResult.close(); }).catch((error) => { // 调用getFirstObject接口失败。 console.error('get first object failed with error: ' + error); }); }).catch((error) => { // 调用getFileAssets接口失败。 console.error('get file assets failed with error: ' + error); }); } ``` ### on8+ on(type: 'deviceChange'|'albumChange'|'imageChange'|'audioChange'|'videoChange'|'fileChange'|'remoteFileChange', callback: Callback<void>): void 打开媒体库变更通知，使用callback方式返回异步结果。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------- | ---- | ---------------------------------------- | | type | 'deviceChange'|
'albumChange'|
'imageChange'|
'audioChange'|
'videoChange'|
'fileChange'|
'remoteFileChange' | 是 | 媒体类型
'deviceChange'： 注册设备变更
'albumChange'： 相册变更
'imageChange'： 图片文件变更
'audioChange'：  音频文件变更
'videoChange'：  视频文件变更
'fileChange'：  文件变更
'remoteFileChange'： 注册设备上文件变更。 | | callback | Callback<void> | 是 | callbac返回空。 | **示例：** ```js media.on('imageChange', () => { // image file had changed, do something. }); ``` ### off8+ off(type: 'deviceChange'|'albumChange'|'imageChange'|'audioChange'|'videoChange'|'fileChange'|'remoteFileChange', callback?: Callback<void>): void 关闭媒体库变更通知，使用callback方式返回异步结果。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------- | ---- | ---------------------------------------- | | type | 'deviceChange'|
'albumChange'|
'imageChange'|
'audioChange'|
'videoChange'|
'fileChange'|
'remoteFileChange' | 是 | 媒体类型
'deviceChange'： 注册设备变更
'albumChange'： 相册变更
'imageChange'： 图片文件变更
'audioChange'：  音频文件变更
'videoChange'：  视频文件变更
'fileChange'：  文件变更
'remoteFileChange'： 注册设备上文件变更。 | | callback | Callback<void> | 否 | callback返回空。 | **示例：** ```js media.off('imageChange', () => { // stop listening successfully. }); ``` ### createAsset8+ createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void 创建媒体资源，使用callback方式返回结果。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | | mediaType | [MediaType](#mediatype8) | 是 | 媒体类型。 | | displayName | string | 是 | 展示文件名。 | | relativePath | string | 是 | 文件保存路径，可以通过[getPublicDirectory](#getpublicdirectory8)获取不同类型文件的保存路径。 | | callback | AsyncCallback<[FileAsset](#fileasset7)> | 是 | callback返回创建的媒体资源FileAsset对象。 | **示例：** ```js async function example() { // 使用Callback方式创建Image类型文件。 let mediaType = mediaLibrary.MediaType.IMAGE; let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; const path = await media.getPublicDirectory(DIR_IMAGE); media.createAsset(mediaType, 'imageCallBack.jpg', path + 'myPicture/', (error, fileAsset) => { if (fileAsset != undefined) { console.info('createAsset successfully, message'); } else { console.error('createAsset failed with error: ' + error); } }); } ``` ### createAsset8+ createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset> 创建媒体资源，使用Promise方式返回结果。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ------------------------ | ---- | ------------------------------------------------------------ | | mediaType | [MediaType](#mediatype8) | 是 | 媒体类型。 | | displayName | string | 是 | 展示文件名。 | | relativePath | string | 是 | 相对路径，可以通过getPublicDirectory获取不同类型媒体文件的一层目录的relative path。 | **返回值：** | 类型 | 说明 | | ------------------------ | ----------------- | | Promise<[FileAsset](#fileasset7)> | Promise对象，返回创建媒体数据的FileAsset。 | **示例：** ```js async function example() { // 使用Promise方式创建Image类型文件。 let mediaType = mediaLibrary.MediaType.IMAGE; let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; const path = await media.getPublicDirectory(DIR_IMAGE); media.createAsset(mediaType, 'imagePromise.jpg', path + 'myPicture/').then((fileAsset) => { console.info('createAsset successfully, message = ' + JSON.stringify(fileAsset)); }).catch((error) => { console.error('createAsset failed with error: ' + error); }); } ``` ### deleteAsset8+ deleteAsset(uri: string): Promise\ 删除媒体文件资源。 **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.READ_MEDIA 和 ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | --------------- | | uri | string | 是 | 需要删除的媒体文件资源的uri。 | **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | Promise<void> | Promise对象，返回删除的结果。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let fileType = mediaLibrary.MediaType.FILE; let option = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [fileType.toString()], }; const fetchFileResult = await media.getFileAssets(option); let asset = await fetchFileResult.getFirstObject(); if (asset == undefined) { console.error('asset not exist'); return; } media.deleteAsset(asset.uri).then(() => { console.info('deleteAsset successfully'); }).catch((error) => { console.error('deleteAsset failed with error: ' + error); }); fetchFileResult.close(); } ``` ### deleteAsset8+ deleteAsset(uri: string, callback: AsyncCallback\): void 删除媒体文件资源。 **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.READ_MEDIA 和 ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | --------------- | | uri | string | 是 | 需要删除的媒体文件资源的uri。 | |callback |AsyncCallback\| 是 |callback返回空。| **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let fileType = mediaLibrary.MediaType.FILE; let option = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [fileType.toString()], }; const fetchFileResult = await media.getFileAssets(option); let asset = await fetchFileResult.getFirstObject(); if (asset == undefined) { console.error('asset not exist'); return; } media.deleteAsset(asset.uri, (error) => { if (error != undefined) { console.error('deleteAsset failed with error: ' + error); } else { console.info('deleteAsset successfully'); } }); fetchFileResult.close(); } ``` ### getPublicDirectory8+ getPublicDirectory(type: DirectoryType, callback: AsyncCallback<string>): void 获取公共目录路径，使用callback方式返回结果。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------- | ---- | ------------------------- | | type | [DirectoryType](#directorytype8) | 是 | 公共目录类型。 | | callback | AsyncCallback<string> | 是 | callback返回公共目录路径。 | **示例：** ```js let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; media.getPublicDirectory(DIR_CAMERA, (error, dicResult) => { if (dicResult == 'Camera/') { console.info('getPublicDirectory DIR_CAMERA successfully'); } else { console.error('getPublicDirectory DIR_CAMERA failed with error: ' + error); } }); ``` ### getPublicDirectory8+ getPublicDirectory(type: DirectoryType): Promise<string> 获取公共目录路径，使用Promise方式返回结果。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------------------------- | ---- | ------------ | | type | [DirectoryType](#directorytype8) | 是 | 公共目录类型。 | **返回值：** | 类型 | 说明 | | ---------------- | ---------------- | | Promise\ | Promise对象，返回公共目录路径。 | **示例：** ```js async function example() { let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; media.getPublicDirectory(DIR_CAMERA).then((dicResult) => { if (dicResult == 'Camera/') { console.info('getPublicDirectory DIR_CAMERA successfully'); } else { console.error('getPublicDirectory DIR_CAMERA failed'); } }).catch((error) => { console.error('getPublicDirectory failed with error: ' + error); }); } ``` ### getAlbums7+ getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album>>): void 获取相册列表，使用callback 方式返回结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------------- | ---- | --------------------------- | | options | [MediaFetchOptions](#mediafetchoptions7) | 是 | 相册检索条件。 | | callback | AsyncCallback<Array<[Album](#album7)>> | 是 | callback返回获取的Album结果集。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; media.getAlbums(AlbumNoArgsfetchOp, (error, albumList) => { if (albumList != undefined) { console.info('getAlbums successfully: ' + JSON.stringify(albumList)); } else { console.error('getAlbums failed with error: ' + error); } }); } ``` ### getAlbums7+ getAlbums(options: MediaFetchOptions): Promise<Array<Album>> 获取相册列表，使用 promise 方式返回结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------------ | | options | [MediaFetchOptions](#mediafetchoptions7) | 是 | 相册获取条件。 | **返回值：** | 类型 | 说明 | | -------------------------------- | ------------- | | Promise> | Promise对象，返回获取的Album结果集。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; media.getAlbums(AlbumNoArgsfetchOp).then((albumList) => { console.info('getAlbums successfully: ' + JSON.stringify(albumList)); }).catch((error) => { console.error('getAlbums failed with error: ' + error); }); } ``` ### release8+ release(callback: AsyncCallback<void>): void 释放MediaLibrary实例。 当后续不需要使用MediaLibrary实例中的方法时调用。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js media.release(() => { // do something. }); ``` ### release8+ release(): Promise<void> 释放MediaLibrary实例。 当后续不需要使用MediaLibrary实例中的方法时调用。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | Promise<void> | Promise对象，返回空。 | **示例：** ```js media.release(); ``` ### storeMediaAsset storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback<string>): void 保存媒体资源，以异步方法获取保存成功的URI，使用callback形式返回结果。 > **说明**：此接口为API Version 6开始支持，只支持FA模型使用。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------- | ---- | ----------------------- | | option | [MediaAssetOption](#mediaassetoption) | 是 | 媒体资源选项。 | | callback | AsyncCallback<string> | 是 | callback返回保存媒体资源成功后得到的URI。 | **示例：** ```js let option = { src : '/data/storage/el2/base/haps/entry/image.png', mimeType : 'image/*', relativePath : 'Pictures/' }; mediaLibrary.getMediaLibrary().storeMediaAsset(option, (error, value) => { if (error) { console.error('storeMediaAsset failed with error: ' + error); return; } console.info('Media resources stored. '); // Obtain the URI that stores media resources. }); ``` ### storeMediaAsset storeMediaAsset(option: MediaAssetOption): Promise<string> 保存媒体资源，以异步方法获取保存成功的URI，使用Promise形式返回结果。 > **说明**：此接口为API Version 6开始支持，只支持FA模型使用。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------- | ---- | ------- | | option | [MediaAssetOption](#mediaassetoption) | 是 | 媒体资源选项。 | **返回值：** | 类型 | 说明 | | --------------------- | ---------------------------- | | Promise<string> | Promise对象，返回保存媒体资源成功后得到的URI。 | **示例：** ```js let option = { src : '/data/storage/el2/base/haps/entry/image.png', mimeType : 'image/*', relativePath : 'Pictures/' }; mediaLibrary.getMediaLibrary().storeMediaAsset(option).then((value) => { console.info('Media resources stored.'); // Obtain the URI that stores media resources. }).catch((error) => { console.error('storeMediaAsset failed with error: ' + error); }); ``` ### startImagePreview startImagePreview(images: Array<string>, index: number, callback: AsyncCallback<void>): void 启动图片预览界面并限定预览开始显示的图片。可以预览指定序号的单张本地图片（datashare://），也可以预览列表中的所有网络图片（https://）。使用callback方式进行异步回调。 > **说明**： > 此接口为API Version 6开始支持，只支持FA模型使用。 > 建议使用[Image组件](../arkui-ts/ts-basic-components-image.md)替代。
Image组件，可用于本地图片和网络图片的渲染展示。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------------------------------------- | | images | Array<string> | 是 | 预览的图片URI（'https://'，'datashare://'）列表。 | | index | number | 是 | 开始显示的图片序号。 | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js let images = [ 'file://media/xxxx/2', 'file://media/xxxx/3' ]; /* 网络图片使用方式。 let images = [ 'https://media.xxxx.com/image1.jpg', 'https://media.xxxx.com/image2.jpg' ]; */ let index = 1; mediaLibrary.getMediaLibrary().startImagePreview(images, index, (error) => { if (error) { console.error('startImagePreview failed with error: ' + error); return; } console.info('Succeeded in previewing the images.'); }); ``` ### startImagePreview startImagePreview(images: Array<string>, callback: AsyncCallback<void>): void 启动图片预览界面，可以预览列表中首张本地图片（datashare://），也可以预览列表中的所有网络图片（https://）。使用callback方式进行异步回调。 > **说明**： > 此接口为API Version 6开始支持，只支持FA模型使用。 > 建议使用[Image组件](../arkui-ts/ts-basic-components-image.md)替代。
Image组件，可用于本地图片和网络图片的渲染展示。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------------------------------------- | | images | Array<string> | 是 | 预览的图片URI（'https://'，'datashare://'）列表。 | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js let images = [ 'file://media/xxxx/2', 'file://media/xxxx/3' ]; /* 网络图片使用方式。 let images = [ 'https://media.xxxx.com/image1.jpg', 'https://media.xxxx.com/image2.jpg' ]; */ mediaLibrary.getMediaLibrary().startImagePreview(images, (error) => { if (error) { console.error('startImagePreview failed with error: ' + error); return; } console.info('Succeeded in previewing the images.'); }); ``` ### startImagePreview startImagePreview(images: Array<string>, index?: number): Promise<void> 启动图片预览界面并限定预览开始显示的图片。可以预览指定序号的单张本地图片（datashare://），也可以预览列表中的所有网络图片（https://）。使用Promise方式进行异步回调。 > **说明**： > 此接口为API Version 6开始支持，只支持FA模型使用。 > 建议使用[Image组件](../arkui-ts/ts-basic-components-image.md)替代。
Image组件，可用于本地图片和网络图片的渲染展示。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------- | ---- | ---------------------------------------- | | images | Array<string> | 是 | 预览的图片URI（'https://'，'datashare://'）列表。 | | index | number | 否 | 开始显示的图片序号，不选择时默认为0。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------------- | | Promise<void> | Promise对象，返回空。 | **示例：** ```js let images = [ 'file://media/xxxx/2', 'file://media/xxxx/3' ]; /* 网络图片使用方式。 let images = [ 'https://media.xxxx.com/image1.jpg', 'https://media.xxxx.com/image2.jpg' ]; */ let index = 1; mediaLibrary.getMediaLibrary().startImagePreview(images, index).then(() => { console.info('Succeeded in previewing the images.'); }).catch((error) => { console.error('startImagePreview failed with error: ' + error); }); ``` ### startMediaSelect startMediaSelect(option: MediaSelectOption, callback: AsyncCallback<Array<string>>): void 启动媒体选择界面，以异步方法获取选择的媒体URI列表，使用callback形式返回结果。 > **说明**： > 此接口为API Version 6开始支持，只支持FA模型使用。 > 建议使用系统应用图库替代。图库是系统内置的可视资源访问应用，提供图片和视频的管理、浏览等功能，使用方法请参考[OpenHarmony/applications_photos](https://gitee.com/openharmony/applications_photos#4-%E5%85%B8%E5%9E%8B%E6%8E%A5%E5%8F%A3%E7%9A%84%E4%BD%BF%E7%94%A8)。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ------------------------------------ | | option | [MediaSelectOption](#mediaselectoption) | 是 | 媒体选择选项。 | | callback | AsyncCallback<Array<string>> | 是 | callback返回选择的媒体URI列表。 | **示例：** ```js let option : mediaLibrary.MediaSelectOption = { type : 'media', count : 2 }; mediaLibrary.getMediaLibrary().startMediaSelect(option, (error, value) => { if (error) { console.error('startMediaSelect failed with error: ' + error); return; } console.info('Media resources selected.'); // Obtain the media selection value. }); ``` ### startMediaSelect startMediaSelect(option: MediaSelectOption): Promise<Array<string>> 启动媒体选择界面，以异步方法获取选择的媒体URI列表，使用Promise形式返回结果。 > **说明**： > 此接口为API Version 6开始支持，只支持FA模型使用。 > 建议使用系统应用图库替代。图库是系统内置的可视资源访问应用，提供图片和视频的管理、浏览等功能，使用方法请参考[OpenHarmony/applications_photos](https://gitee.com/openharmony/applications_photos#4-%E5%85%B8%E5%9E%8B%E6%8E%A5%E5%8F%A3%E7%9A%84%E4%BD%BF%E7%94%A8)。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | --------------------------------------- | ---- | ------- | | option | [MediaSelectOption](#mediaselectoption) | 是 | 媒体选择选项。 | **返回值：** | 类型 | 说明 | | ---------------------------------- | ---------------------------------------- | | Promise<Array<string>> | Promise对象，返回选择的媒体URI列表。 | **示例：** ```js let option : mediaLibrary.MediaSelectOption = { type : 'media', count : 2 }; mediaLibrary.getMediaLibrary().startMediaSelect(option).then((value) => { console.info('Media resources selected.'); // Obtain the media selection value. }).catch((error) => { console.error('startMediaSelect failed with error: ' + error); }); ``` ### getActivePeers8+ getActivePeers(): Promise\>; 获取在线对端设备的信息，使用Promise方式返回异步结果。 **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.DistributedCore **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | Promise\> | Promise对象，返回获取的所有在线对端设备的PeerInfo。 | **示例：** ```js async function example() { media.getActivePeers().then((devicesInfo) => { if (devicesInfo != undefined) { console.info('get distributed info ' + JSON.stringify(devicesInfo)); } else { console.info('get distributed info is undefined!'); } }).catch((error) => { console.error('get distributed info failed with error: ' + error); }); } ``` ### getActivePeers8+ getActivePeers(callback: AsyncCallback\>): void; 获取在线对端设备的信息，使用callback方式返回异步结果。 **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.DistributedCore **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | callback: AsyncCallback\> | callback返回获取的所有在线对端设备的PeerInfo对象。 | **示例：** ```js async function example() { media.getActivePeers((error, devicesInfo) => { if (devicesInfo != undefined) { console.info('get distributed info ' + JSON.stringify(devicesInfo)); } else { console.error('get distributed failed with error: ' + error); } }); } ``` ### getAllPeers8+ getAllPeers(): Promise\>; 获取所有对端设备的信息，使用Promise方式返回异步结果。 **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.DistributedCore **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | Promise\> | Promise对象，返回获取的所有对端设备的PeerInfo。 | **示例：** ```js async function example() { media.getAllPeers().then((devicesInfo) => { if (devicesInfo != undefined) { console.info('get distributed info ' + JSON.stringify(devicesInfo)); } else { console.info('get distributed info is undefined!'); } }).catch((error) => { console.error('get distributed info failed with error: ' + error); }); } ``` ### getAllPeers8+ getAllPeers(callback: AsyncCallback\>): void; 获取所有对端设备的信息，使用callback方式返回异步结果。 **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.DistributedCore **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | callback: AsyncCallback\> | callback返回获取的所有对端设备的PeerInfo对象。 | **示例：** ```js async function example() { media.getAllPeers((error, devicesInfo) => { if (devicesInfo != undefined) { console.info('get distributed info ' + JSON.stringify(devicesInfo)); } else { console.error('get distributed failed with error: ' + error); } }); } ``` ## FileAsset7+ 提供封装文件属性的方法。 > **说明：** > > 1. title字段默认为去掉后缀的文件名，音频和视频文件会尝试解析文件内容，部分设备写入后在触发扫描时会被还原。 > 2. orientation字段部分设备可能不支持修改，建议使用image组件的[ModifyImageProperty](js-apis-image.md#modifyimageproperty9)接口。 ### 属性 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | | id | number | 是 | 否 | 文件资源编号。 | | uri | string | 是 | 否 | 文件资源uri（如：file://media/image/2)。 | | mimeType | string | 是 | 否 | 文件扩展属性。 | | mediaType8+ | [MediaType](#mediatype8) | 是 | 否 | 媒体类型。 | | displayName | string | 是 | 是 | 显示文件名，包含后缀名。 | | title | string | 是 | 是 | 文件标题。 | | relativePath8+ | string | 是 | 是 | 相对公共目录路径。 | | parent8+ | number | 是 | 否 | 父目录id。 | | size | number | 是 | 否 | 文件大小（单位：字节）。 | | dateAdded | number | 是 | 否 | 添加日期（添加文件时间到1970年1月1日的秒数值）。 | | dateModified | number | 是 | 否 | 修改日期（修改文件时间到1970年1月1日的秒数值，修改文件名不会改变此值，当文件内容发生修改时才会更新）。| | dateTaken | number | 是 | 否 | 拍摄日期（文件拍照时间到1970年1月1日的秒数值）。 | | artist8+ | string | 是 | 否 | 作者。 | | audioAlbum8+ | string | 是 | 否 | 专辑。 | | width | number | 是 | 否 | 图片宽度（单位：像素）。 | | height | number | 是 | 否 | 图片高度（单位：像素）。 | | orientation | number | 是 | 是 | 图片显示方向（顺时针旋转角度，如0，90，180 单位：度）。 | | duration8+ | number | 是 | 否 | 持续时间（单位：毫秒）。 | | albumId | number | 是 | 否 | 文件所归属的相册编号。 | | albumUri8+ | string | 是 | 否 | 文件所归属相册uri。 | | albumName | string | 是 | 否 | 文件所归属相册名称。 | ### isDirectory8+ isDirectory(callback: AsyncCallback<boolean>): void 判断fileAsset是否为目录，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ------------------- | | callback | AsyncCallback<boolean> | 是 | callback返回boolean值，值为true则是目录，值为false则非目录。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.isDirectory((error, isDirectory) => { if (error) { console.error('isDirectory failed with error: ' + error); } else { console.info('isDirectory result:' + isDirectory); } }); fetchFileResult.close(); } ``` ### isDirectory8+ isDirectory():Promise<boolean> 判断fileAsset是否为目录，使用Promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ---------------------- | ---------------------------- | | Promise<boolean> | Promise对象，返回boolean值，值为true则是目录，值为false则非目录。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.isDirectory().then((isDirectory) => { console.info('isDirectory result:' + isDirectory); }).catch((error) => { console.error('isDirectory failed with error: ' + error); }); fetchFileResult.close(); } ``` ### commitModify8+ commitModify(callback: AsyncCallback<void>): void 修改文件的元数据，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ----- | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.title = 'newtitle'; asset.commitModify(() => { console.info('commitModify successfully'); }); fetchFileResult.close(); } ``` ### commitModify8+ commitModify(): Promise<void> 修改文件的元数据，使用promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ------------------- | ---------- | | Promise<void> | Promise对象，返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.title = 'newtitle'; await asset.commitModify(); fetchFileResult.close(); } ``` ### open8+ open(mode: string, callback: AsyncCallback<number>): void 打开当前文件，使用callback方式返回异步结果。 **注意**：以 'w' 模式打开文件时，返回的fd无法进行读取。但由于不同文件系统实现上的差异，部分用户态文件系统在 'w' 模式打开时会允许用fd读取。若有针对fd的读写行为，建议使用 'rw' 模式打开文件。当前写操作是互斥的操作，写操作完成后需要调用close进行释放。 **需要权限**：ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------- | ---- | ----------------------------------- | | mode | string | 是 | 打开文件方式，如：'r'（只读）, 'w'（只写）, 'rw'（读写）。 | | callback | AsyncCallback<number> | 是 | callback返回文件描述符。 | **示例：** ```js async function example() { let mediaType = mediaLibrary.MediaType.IMAGE; let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; const path = await media.getPublicDirectory(DIR_IMAGE); const asset = await media.createAsset(mediaType, 'image00003.jpg', path); asset.open('rw', (error, fd) => { if (fd > 0) { asset.close(fd); } else { console.error('File Open failed with error: ' + error); } }); } ``` ### open8+ open(mode: string): Promise<number> 打开当前文件，使用promise方式返回异步结果。 **注意**：以 'w' 模式打开文件时，返回的fd无法进行读取。但由于不同文件系统实现上的差异，部分用户态文件系统在 'w' 模式打开时会允许用fd读取。若有针对fd的读写行为，建议使用 'rw' 模式打开文件。当前写操作是互斥的操作，写操作完成后需要调用close进行释放。 **需要权限**：ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ----------------------------------- | | mode | string | 是 | 打开文件方式，如：'r'（只读）, 'w'（只写）, 'rw'（读写）。 | **返回值：** | 类型 | 说明 | | --------------------- | ------------- | | Promise<number> | Promise对象，返回文件描述符。 | **示例：** ```js async function example() { let mediaType = mediaLibrary.MediaType.IMAGE; let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; const path = await media.getPublicDirectory(DIR_IMAGE); const asset = await media.createAsset(mediaType, 'image00003.jpg', path); asset.open('rw').then((fd) => { console.info('File open fd: ' + fd); }).catch((error) => { console.error('File open failed with error: ' + error); }); } ``` ### close8+ close(fd: number, callback: AsyncCallback<void>): void 关闭当前文件，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ----- | | fd | number | 是 | 文件描述符。 | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.open('rw').then((fd) => { console.info('File open fd: ' + fd); asset.close(fd, (error) => { if (error) { console.error('asset.close failed with error: ' + error); } else { console.info('asset.close successfully'); } }); }).catch((error) => { console.error('File open failed with error: ' + error); }); fetchFileResult.close(); } ``` ### close8+ close(fd: number): Promise<void> 关闭当前文件，使用promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ----- | | fd | number | 是 | 文件描述符。 | **返回值：** | 类型 | 说明 | | ------------------- | ---------- | | Promise<void> | Promise对象，返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.open('rw').then((fd) => { console.info('File fd!' + fd); asset.close(fd).then(() => { console.info('asset.close successfully'); }).catch((closeErr) => { console.error('asset.close fail, closeErr: ' + closeErr); }); }).catch((error) => { console.error('open File failed with error: ' + error); }); fetchFileResult.close(); } ``` ### getThumbnail8+ getThumbnail(callback: AsyncCallback<image.PixelMap>): void 获取文件的缩略图，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------- | ---- | ---------------- | | callback | AsyncCallback<image.PixelMap> | 是 | callback返回缩略图的PixelMap。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.getThumbnail((error, pixelmap) => { if (error) { console.error('mediaLibrary getThumbnail failed with error: ' + error); } else { console.info('mediaLibrary getThumbnail Successful, pixelmap ' + JSON.stringify(pixelmap)); } }); fetchFileResult.close(); } ``` ### getThumbnail8+ getThumbnail(size: Size, callback: AsyncCallback<image.PixelMap>): void 获取文件的缩略图，传入缩略图尺寸，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------- | ---- | ---------------- | | size | [Size](#size8) | 是 | 缩略图尺寸。 | | callback | AsyncCallback<image.PixelMap> | 是 | callback返回缩略图的PixelMap。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let size = { width: 720, height: 720 }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.getThumbnail(size, (error, pixelmap) => { if (error) { console.error('mediaLibrary getThumbnail failed with error: ' + error); } else { console.info('mediaLibrary getThumbnail Successful, pixelmap ' + JSON.stringify(pixelmap)); } }); fetchFileResult.close(); } ``` ### getThumbnail8+ getThumbnail(size?: Size): Promise<image.PixelMap> 获取文件的缩略图，传入缩略图尺寸，使用promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | -------------- | ---- | ----- | | size | [Size](#size8) | 否 | 缩略图尺寸。 | **返回值：** | 类型 | 说明 | | ----------------------------- | --------------------- | | Promise<image.PixelMap> | Promise对象，返回缩略图的PixelMap。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let size = { width: 720, height: 720 }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.getThumbnail(size).then((pixelmap) => { console.info('mediaLibrary getThumbnail Successful, pixelmap ' + JSON.stringify(pixelmap)); }).catch((error) => { console.error('mediaLibrary getThumbnail failed with error: ' + error); }); fetchFileResult.close(); } ``` ### favorite8+ favorite(isFavorite: boolean, callback: AsyncCallback<void>): void 将文件设置为收藏文件，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------------------------- | ---- | ---------------------------------- | | isFavorite | boolean | 是 | 是否设置为收藏文件， true：设置为收藏文件，false：取消收藏。 | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.favorite(true,(error) => { if (error) { console.error('mediaLibrary favorite failed with error: ' + error); } else { console.info('mediaLibrary favorite Successful'); } }); fetchFileResult.close(); } ``` ### favorite8+ favorite(isFavorite: boolean): Promise<void> 将文件设置为收藏文件，使用promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------- | ---- | ---------------------------------- | | isFavorite | boolean | 是 | 是否设置为收藏文件， true：设置为收藏文件，false：取消收藏。 | **返回值：** | 类型 | 说明 | | ------------------- | ---------- | | Promise<void> | Promise对象，返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.favorite(true).then(() => { console.info('mediaLibrary favorite Successful'); }).catch((error) => { console.error('mediaLibrary favorite failed with error: ' + error); }); fetchFileResult.close(); } ``` ### isFavorite8+ isFavorite(callback: AsyncCallback<boolean>): void 判断该文件是否为收藏文件，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ----------- | | callback | AsyncCallback<boolean> | 是 | callback返回boolean值，值为true则为已收藏，值为false则为未收藏。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.isFavorite((error, isFavorite) => { if (error) { console.error('mediaLibrary favoriisFavoritete failed with error: ' + error); } else { console.info('mediaLibrary isFavorite Successful, isFavorite result: ' + isFavorite); } }); fetchFileResult.close(); } ``` ### isFavorite8+ isFavorite():Promise<boolean> 判断该文件是否为收藏文件，使用promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ---------------------- | ------------------ | | Promise<boolean> | Promise对象，返回boolean值，值为true则为已收藏，值为false则为未收藏。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.isFavorite().then((isFavorite) => { console.info('mediaLibrary isFavorite Successful, isFavorite result: ' + isFavorite); }).catch((error) => { console.error('mediaLibrary favoriisFavoritete failed with error: ' + error); }); fetchFileResult.close(); } ``` ### trash8+ trash(isTrash: boolean, callback: AsyncCallback<void>): void 当文件被定位时，将文件放到垃圾文件夹，使用callback方式返回异步结果。 放入垃圾文件夹的文件不会被真正删除，可以通过isTrash = false参数恢复成正常文件。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | --------- | | isTrash | boolean | 是 | 是否设置为垃圾文件。 | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.trash(true, (error) => { if (error) { console.error('mediaLibrary trash failed with error: ' + error); } else { console.info('mediaLibrary trash Successful'); } }); fetchFileResult.close(); } ``` ### trash8+ trash(isTrash: boolean): Promise<void> 当文件被定位时，将文件放到垃圾文件夹，使用promise方式返回异步结果。 放入垃圾文件夹的文件不会被真正删除，可以通过isTrash = false参数恢复成正常文件。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | --------- | | isTrash | boolean | 是 | 是否设置为垃圾文件。 | **返回值：** | 类型 | 说明 | | ------------------- | ---------- | | Promise<void> | Promise对象，返回空 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.trash(true).then(() => { console.info('trash successfully'); }).catch((error) => { console.error('trash failed with error: ' + error); }); fetchFileResult.close(); } ``` ### isTrash8+ isTrash(callback: AsyncCallback<boolean>): void 当文件被定位，判断文件是否为垃圾文件，使用callback方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | --------------- | | callback | AsyncCallback<boolean> | 是 | callback返回boolean值，值为true则为垃圾文件，值为false则为非垃圾文件。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.isTrash((error, isTrash) => { if (error) { console.error('Failed to get trash state failed with error: ' + error); return; } console.info('Get trash state successfully, isTrash result: ' + isTrash); }); fetchFileResult.close(); } ``` ### isTrash8+ isTrash():Promise<boolean> 当文件被定位，判断文件是否为垃圾文件，使用promise方式返回异步结果。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ------------------- | -------------------- | | Promise<void> | Promise对象，返回boolean值，值为true则为垃圾文件，值为false则为非垃圾文件。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.isTrash().then((isTrash) => { console.info('isTrash result: ' + isTrash); }).catch((error) => { console.error('isTrash failed with error: ' + error); }); fetchFileResult.close(); } ``` ## FetchFileResult7+ 文件检索结果集。 ### getCount7+ getCount(): number 获取文件检索结果中的文件总数。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ------ | -------- | | number | 检索到的文件总数。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let fileType = mediaLibrary.MediaType.FILE; let getFileCountOneOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [fileType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getFileCountOneOp); const fetchCount = fetchFileResult.getCount(); console.info('fetchCount result: ' + fetchCount); fetchFileResult.close(); } ``` ### isAfterLast7+ isAfterLast(): boolean 检查结果集是否指向最后一行。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ------- | ---------------------------------- | | boolean | 当读到最后一条记录后，后续没有记录返回true，否则返回false。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); const fetchCount = fetchFileResult.getCount(); console.info('mediaLibrary fetchFileResult.getCount, count:' + fetchCount); let fileAsset = await fetchFileResult.getFirstObject(); for (var i = 1; i < fetchCount; i++) { fileAsset = await fetchFileResult.getNextObject(); if(i == fetchCount - 1) { var result = fetchFileResult.isAfterLast(); console.info('mediaLibrary fileAsset isAfterLast result: ' + result); fetchFileResult.close(); } } } ``` ### close7+ close(): void 释放 FetchFileResult 实例并使其失效。无法调用其他方法。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.close(); } ``` ### getFirstObject7+ getFirstObject(callback: AsyncCallback<FileAsset>): void 获取文件检索结果中的第一个文件资产。此方法使用回调返回FileAsset。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------------------------- | ---- | ------------------------------------------- | | callback | AsyncCallback<[FileAsset](#fileasset7)> | 是 | callback返回文件检索结果集中第一个FileAsset对象。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getFirstObject((error, fileAsset) => { if (error) { console.error('fetchFileResult getFirstObject failed with error: ' + error); return; } console.info('getFirstObject successfully, displayName : ' + fileAsset.displayName); fetchFileResult.close(); }) } ``` ### getFirstObject7+ getFirstObject(): Promise<FileAsset> 获取文件检索结果中的第一个文件资产。此方法使用Promise方式返回FileAsset。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | --------------------------------------- | -------------------------- | | Promise<[FileAsset](#fileasset7)> | Promise对象，返回文件检索结果集中第一个FileAsset。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getFirstObject().then((fileAsset) => { console.info('getFirstObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }).catch((error) => { console.error('getFirstObject failed with error: ' + error); }); } ``` ### getNextObject7+ getNextObject(callback: AsyncCallback<FileAsset>): void 获取文件检索结果中的下一个文件资产，此方法使用callback形式返回结果。 > **说明**： 在使用前需要先使用[getFirstObject](#getfirstobject7)接口获取第一个文件资产，然后使用[isAfterLast](#isafterlast7)确认文件检索集当前不是指向最后一个时方可使用此接口。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------------------------------- | ---- | ----------------------------------------- | | callbacke | AsyncCallback<[FileAsset](#fileasset7)> | 是 | callback返回文件检索结果集中下一个FileAsset对象。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); let fileAsset = await fetchFileResult.getFirstObject(); console.log('fetchFileResult getFirstObject successfully, displayName: ' + fileAsset.displayName); if (!fetchFileResult.isAfterLast()) { fetchFileResult.getNextObject((error, fileAsset) => { if (error) { console.error('fetchFileResult getNextObject failed with error: ' + error); return; } console.log('fetchFileResult getNextObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }) } } ``` ### getNextObject7+ getNextObject(): Promise<FileAsset> 获取文件检索结果中的下一个文件资产。此方法使用promise方式来异步返回FileAsset。 > **说明**： 在使用前需要先使用[getFirstObject](#getfirstobject7)接口获取第一个文件资产，然后使用[isAfterLast](#isafterlast7)确认文件检索集当前不是指向最后一个时方可使用此接口。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | --------------------------------------- | ----------------- | | Promise<[FileAsset](#fileasset7)> | Promise对象，返回文件检索结果集中下一个FileAsset。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); let fileAsset = await fetchFileResult.getFirstObject(); console.log('fetchFileResult getFirstObject successfully, displayName: ' + fileAsset.displayName); if (!fetchFileResult.isAfterLast()) { fetchFileResult.getNextObject().then((fileAsset) => { console.info('fetchFileResult getNextObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }).catch((error) => { console.error('fetchFileResult getNextObject failed with error: ' + error); }) } } ``` ### getLastObject7+ getLastObject(callback: AsyncCallback<FileAsset>): void 获取文件检索结果中的最后一个文件资产。此方法使用callback回调来返回FileAsset。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------------------------- | ---- | --------------------------- | | callback | AsyncCallback<[FileAsset](#fileasset7)> | 是 | callback返回文件检索结果集中最后一个FileAsset对象。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getLastObject((error, fileAsset) => { if (error) { console.error('getLastObject failed with error: ' + error); return; } console.info('getLastObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }) } ``` ### getLastObject7+ getLastObject(): Promise<FileAsset> 获取文件检索结果中的最后一个文件资产。此方法使用Promise方式来返回FileAsset。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | --------------------------------------- | ----------------- | | Promise<[FileAsset](#fileasset7)> | Promise对象，返回文件检索结果集中最后一个FileAsset。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getLastObject().then((fileAsset) => { console.info('getLastObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }).catch((error) => { console.error('getLastObject failed with error: ' + error); }); } ``` ### getPositionObject7+ getPositionObject(index: number, callback: AsyncCallback<FileAsset>): void 获取文件检索结果中具有指定索引的文件资产。此方法使用回调来返回FileAsset。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ------------------ | | index | number | 是 | 要获取的文件的索引，从0开始(注意该值要小于文件检索集的count值)。 | | callback | AsyncCallback<[FileAsset](#fileasset7)> | 是 | callback返回文件检索结果集中指定索引处的FileAsset对象。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getPositionObject(0, (error, fileAsset) => { if (error) { console.error('getPositionObject failed with error: ' + error); return; } console.info('getPositionObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }) } ``` ### getPositionObject7+ getPositionObject(index: number): Promise<FileAsset> 获取文件检索结果中具有指定索引的文件资产。此方法使用Promise形式返回文件Asset。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | -------------- | | index | number | 是 | 要获取的文件的索引，从0开始(注意该值要小于文件检索集的count值)。 | **返回值：** | 类型 | 说明 | | --------------------------------------- | ----------------- | | Promise<[FileAsset](#fileasset7)> | Promise对象，返回文件检索结果集中指定索引处的FileAsset。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getPositionObject(0).then((fileAsset) => { console.info('getPositionObject successfully, displayName: ' + fileAsset.displayName); fetchFileResult.close(); }).catch((error) => { console.error('getPositionObject failed with error: ' + error); }); } ``` ### getAllObject7+ getAllObject(callback: AsyncCallback<Array<FileAsset>>): void 获取文件检索结果中的所有文件资产。此方法使用Callback回调来返回FileAsset结果集。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | -------------------- | | callback | AsyncCallback<Array<[FileAsset](#fileasset7)>> | 是 | callback返回文件检索结果集中所有的FileAsset对象。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getAllObject((error, fileAssetList) => { if (error) { console.error('getAllObject failed with error: ' + error); return; } for (let i = 0; i < fetchFileResult.getCount(); i++) { console.info('getAllObject fileAssetList ' + i + ' displayName: ' + fileAssetList[i].displayName); } fetchFileResult.close(); }) } ``` ### getAllObject7+ getAllObject(): Promise<Array<FileAsset>> 获取文件检索结果中的所有文件资产。此方法使用Promise来返回FileAsset结果集。 **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ---------------------------------------- | --------------------- | | Promise<Array<[FileAsset](#fileasset7)>> | Promise对象，返回文件检索结果集中所有的FileAsset。 | **示例：** ```js async function example() { let fileKeyObj = mediaLibrary.FileKey; let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + ' DESC', }; let fetchFileResult = await media.getFileAssets(getImageOp); fetchFileResult.getAllObject().then((fileAssetList) => { for (let i = 0; i < fetchFileResult.getCount(); i++) { console.info('getAllObject fileAssetList ' + i + ' displayName: ' + fileAssetList[i].displayName); } fetchFileResult.close(); }).catch((error) => { console.error('getAllObject failed with error: ' + error); }); } ``` ## Album7+ 实体相册 ### 属性 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ------------ | ------ | ---- | ---- | ------- | | albumId | number | 是 | 否 | 相册编号。 | | albumName | string | 是 | 是 | 相册名称。 | | albumUri8+ | string | 是 | 否 | 相册Uri。 | | dateModified | number | 是 | 否 | 修改日期。 | | count8+ | number | 是 | 否 | 相册中文件数量。 | | relativePath8+ | string | 是 | 否 | 相对路径。 | | coverUri8+ | string | 是 | 否 | 封面文件Uri。 | ### commitModify8+ commitModify(callback: AsyncCallback<void>): void 更新相册属性修改到数据库中。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | callback返回空。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; const albumList = await media.getAlbums(AlbumNoArgsfetchOp); const album = albumList[0]; album.albumName = 'hello'; album.commitModify((error) => { if (error) { console.error('commitModify failed with error: ' + error); return; } console.info('commitModify successful.'); }); } ``` ### commitModify8+ commitModify(): Promise<void> 更新相册属性修改到数据库中。 **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **返回值：** | 类型 | 说明 | | ------------------- | ------------ | | Promise<void> | Promise对象，返回空。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; const albumList = await media.getAlbums(AlbumNoArgsfetchOp); const album = albumList[0]; album.albumName = 'hello'; album.commitModify().then(() => { console.info('commitModify successfully'); }).catch((error) => { console.error('commitModify failed with error: ' + error); }); } ``` ### getFileAssets7+ getFileAssets(callback: AsyncCallback<FetchFileResult>): void 按照检索条件获取相册中的文件。此方法使用Callback回调来返回文件结果集。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------------------------------- | ---- | ----------------------------------- | | callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | 是 | callback返回相册中的文件检索结果集。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; // 获取符合检索要求的相册，返回相册列表。 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); const album = albumList[0]; // 取到相册列表中的一个相册，获取此相册中所有符合媒体检索选项的媒体资源。 album.getFileAssets((error, fetchFileResult) => { if (error) { console.error('album getFileAssets failed with error: ' + error); return; } let count = fetchFileResult.getCount(); console.info('album getFileAssets successfully, count: ' + count); fetchFileResult.close(); }); } ``` ### getFileAssets7+ getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void 按照检索条件获取相册中的文件。此方法使用Callback回调来返回文件结果集。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------------------------------- | ---- | ----------------------------------- | | options | [MediaFetchOptions](#mediafetchoptions7) | 是 | 媒体检索选项。 | | callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | 是 | callback返回相册中的文件检索结果集。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; let fileNoArgsfetchOp = { selections: '', selectionArgs: [], }; // 获取符合检索要求的相册，返回相册列表。 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); const album = albumList[0]; // 取到相册列表中的一个相册，获取此相册中所有符合媒体检索选项的媒体资源。 album.getFileAssets(fileNoArgsfetchOp, (error, fetchFileResult) => { if (error) { console.error('album getFileAssets failed with error: ' + error); return; } let count = fetchFileResult.getCount(); console.info('album getFileAssets successfully, count: ' + count); fetchFileResult.close(); }); } ``` ### getFileAssets7+ getFileAssets(options?: MediaFetchOptions): Promise<FetchFileResult> 按照检索条件获取相册中的文件。此方法使用异步Promise来返回文件结果集。 **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | -------------- | | options | [MediaFetchOptions](#mediafetchoptions7) | 否 | 媒体检索选项。 | **返回值：** | 类型 | 说明 | | --------------------------------------------- | ------------------------- | | Promise<[FetchFileResult](#fetchfileresult7)> | Promise对象，返回相册中的文件检索结果集。 | **示例：** ```js async function example() { // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', selectionArgs: ['新建相册1'], }; let fileNoArgsfetchOp = { selections: '', selectionArgs: [], }; // 获取符合检索要求的相册，返回相册列表。 const albumList = await media.getAlbums(AlbumNoArgsfetchOp); const album = albumList[0]; // 取到相册列表中的一个相册，获取此相册中所有符合媒体检索选项的媒体资源。 album.getFileAssets(fileNoArgsfetchOp).then((fetchFileResult) => { let count = fetchFileResult.getCount(); console.info('album getFileAssets successfully, count: ' + count); fetchFileResult.close(); }).catch((error) => { console.error('album getFileAssets failed with error: ' + error); }); } ``` ## PeerInfo8+ 注册设备的信息。 **系统接口**：此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.DistributedCore | 名称 | 类型 | 可读 | 可写 | 说明 | | ---------- | -------------------------- | ---- | ---- | ---------------- | | deviceName | string | 是 | 否 | 注册设备的名称。 | | networkId | string | 是 | 否 | 注册设备的网络ID。 | | deviceType | [DeviceType](#devicetype8) | 是 | 否 | 设备类型。 | | isOnline | boolean | 是 | 否 | 是否在线。 | ## MediaType8+ 枚举，媒体类型。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 值 | 说明 | | ----- | ---- | ---- | | FILE | 0 | 文件。 | | IMAGE | 1 | 图片。 | | VIDEO | 2 | 视频。| | AUDIO | 3 | 音频。 | ## FileKey8+ 枚举，文件关键信息。 > **说明：** > bucket_id字段在文件重命名或移动后可能会发生变化，开发者使用前需要重新获取。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 值 | 说明 | | ------------- | ------------------- | ---------------------------------------------------------- | | ID | 'file_id' | 文件编号。 | | RELATIVE_PATH | 'relative_path' | 相对公共目录路径。 | | DISPLAY_NAME | 'display_name' | 显示名字。 | | PARENT | 'parent' | 父目录id。 | | MIME_TYPE | 'mime_type' | 文件扩展属性(如：image/*、video/*、file/*)。 | | MEDIA_TYPE | 'media_type' | 媒体类型。 | | SIZE | 'size' | 文件大小（单位：字节）。 | | DATE_ADDED | 'date_added' | 添加日期（添加文件时间到1970年1月1日的秒数值）。 | | DATE_MODIFIED | 'date_modified' | 修改日期（修改文件时间到1970年1月1日的秒数值，修改文件名不会改变此值，当文件内容发生修改时才会更新）。 | | DATE_TAKEN | 'date_taken' | 拍摄日期（文件拍照时间到1970年1月1日的秒数值）。 | | TITLE | 'title' | 文件标题。 | | ARTIST | 'artist' | 作者。 | | AUDIOALBUM | 'audio_album' | 专辑。 | | DURATION | 'duration' | 持续时间（单位：毫秒）。 | | WIDTH | 'width' | 图片宽度（单位：像素）。 | | HEIGHT | 'height' | 图片高度（单位：像素）。 | | ORIENTATION | 'orientation' | 图片显示方向，即顺时针旋转角度，如0，90，180。（单位：度）。 | | ALBUM_ID | 'bucket_id' | 文件所归属的相册编号。 | | ALBUM_NAME | 'bucket_display_name' | 文件所归属相册名称。 | ## DirectoryType8+ 枚举，目录类型。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 值 | 说明 | | ------------- | --- | ------------------ | | DIR_CAMERA | 0 | 表示Camera文件路径。 | | DIR_VIDEO | 1 | 表示视频路径。 | | DIR_IMAGE | 2 | 表示图片路径。 | | DIR_AUDIO | 3 | 表示音频路径。 | | DIR_DOCUMENTS | 4 | 表示文档路径。 | | DIR_DOWNLOAD | 5 | 表示下载路径。 | ## DeviceType8+ 枚举，设备类型。 **系统接口**：此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.DistributedCore | 名称 | 值 | 说明 | | ------------ | --- | ---------- | | TYPE_UNKNOWN | 0 | 未识别设备。 | | TYPE_LAPTOP | 1 | 笔记本电脑。 | | TYPE_PHONE | 2 | 手机。 | | TYPE_TABLET | 3 | 平板电脑。 | | TYPE_WATCH | 4 | 智能手表。 | | TYPE_CAR | 5 | 车载设备。 | | TYPE_TV | 6 | 电视设备。 | ## MediaFetchOptions7+ 检索条件。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ----------------------- | ------------------- | ---- | ---- | ------------------------------------------------------------ | | selections | string | 是 | 是 | 检索条件，使用[FileKey](#filekey8)中的枚举值作为检索条件的列名。示例：
selections: mediaLibrary.FileKey.MEDIA_TYPE + '= ? OR ' + mediaLibrary.FileKey.MEDIA_TYPE + '= ?', | | selectionArgs | Array<string> | 是 | 是 | 检索条件的值，对应selections中检索条件列的值。
示例：
selectionArgs: [mediaLibrary.MediaType.IMAGE.toString(), mediaLibrary.MediaType.VIDEO.toString()], | | order | string | 是 | 是 | 检索结果排序方式，使用[FileKey](#filekey8)中的枚举值作为检索结果排序的列，可以用升序或降序排列。示例：
升序排列：order: mediaLibrary.FileKey.DATE_ADDED + ' ASC'
降序排列：order: mediaLibrary.FileKey.DATE_ADDED + ' DESC' | | uri8+ | string | 是 | 是 | 文件URI。 | | networkId8+ | string | 是 | 是 | 注册设备网络ID。 | | extendArgs8+ | string | 是 | 是 | 扩展的检索参数，目前没有扩展检索参数。 | ## Size8+ 图片尺寸。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ------ | ------ | ---- | ---- | -------- | | width | number | 是 | 是 | 宽（单位：像素）。 | | height | number | 是 | 是 | 高（单位：像素）。 | ## MediaAssetOption 媒体资源选项。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ------------ | ------ | ---- | ---- | ------------------------------------------------------------ | | src | string | 是 | 是 | 本地文件应用沙箱路径。 | | mimeType | string | 是 | 是 | 媒体MIME（Multipurpose Internet Mail Extensions）类型。
包括：'image/\*'、'video/\*'、'audio/\*'、 'file\*'。 | | relativePath | string | 是 | 是 | 自定义媒体资源保存位置，例：Pictures/ 不填则保存到默认路径。
image类型默认路径Pictures/
video类型默认路径Videos/
audio类型默认路径Audios/
file类型默认路径Documents/ 。 | ## MediaSelectOption 媒体资源类型选项。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.MediaLibrary.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ----- | ------ | ---- | ---- | -------------------- | | type | 'image' | 'video' | 'media' | 是 | 是 | 媒体类型，包括：image, video, media，当前仅支持media类型。 | | count | number | 是 | 是 | 可以选择媒体数量的最大值，count = 1表示单选，count大于1表示多选。 |