diff --git a/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md b/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md index 8a018b9032da3414e2a2c9c614def2b31c34def9..6c181358df81b5d44dc7b123c9bea33d62f3865c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md +++ b/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md @@ -82,6 +82,9 @@ getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileRe 获取文件资源，使用callback方式返回异步结果。 +> **说明：** +> 在API version 10上，摒弃了物理目录作为相册的设计，采用了逻辑相册的设计，一个相册中可以添加多个文件，一个文件也可以在多个相册中呈现。新的设计将带来parent、albumId、albumUri和albumName属性使用上的不兼容，无法作为MediaFetchOptions的参数在getFileAssets接口中使用。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -150,6 +153,9 @@ getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> 获取文件资源，使用Promise方式返回结果。 +> **说明：** +> 在API version 10上，摒弃了物理目录作为相册的设计，采用了逻辑相册的设计，一个相册中可以添加多个文件，一个文件也可以在多个相册中呈现。新的设计将带来parent、albumId、albumUri和albumName属性使用上的不兼容，无法作为MediaFetchOptions的参数在getFileAssets接口中使用。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -265,6 +271,9 @@ createAsset(mediaType: MediaType, displayName: string, relativePath: string, cal 创建媒体资源，使用callback方式返回结果。 +> **说明：** +> 由于API version 10的SDK上relativePath和相册没有关联关系，文件创建成功后，relativePath的最后一级目录不会作为相册呈现。变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -302,6 +311,9 @@ createAsset(mediaType: MediaType, displayName: string, relativePath: string): Pr 创建媒体资源，使用Promise方式返回结果。 +> **说明：** +> 由于API version 10的SDK上relativePath和相册没有关联关系，文件创建成功后，relativePath的最后一级目录不会作为相册呈现。变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -502,6 +514,9 @@ getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album& 获取相册列表，使用callback 方式返回结果。 +> **说明：** +> 由于API version 10的SDK上relativePath和相册没有关联关系，在使用getAlbums时不支持relativePath作为查询条件，当前仅支持“Camera”和“ScreenShots”两类相册，变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -517,10 +532,9 @@ getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album& ```js async function example() { - // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', - selectionArgs: ['新建相册1'], + selectionArgs: ['Camera'], }; media.getAlbums(AlbumNoArgsfetchOp, (error, albumList) => { if (albumList != undefined) { @@ -538,6 +552,9 @@ getAlbums(options: MediaFetchOptions): Promise<Array<Album>> 获取相册列表，使用 promise 方式返回结果。 +> **说明：** +> 由于API version 10的SDK上relativePath和相册没有关联关系，在使用getAlbums时不支持relativePath作为查询条件.当前仅支持“Camera”和“ScreenShots”两类相册，变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -558,10 +575,9 @@ getAlbums(options: MediaFetchOptions): Promise<Array<Album>> ```js async function example() { - // 获取相册需要先预置相册和资源，示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', - selectionArgs: ['新建相册1'], + selectionArgs: ['Camera'], }; media.getAlbums(AlbumNoArgsfetchOp).then((albumList) => { console.info('getAlbums successfully: ' + JSON.stringify(albumList)); @@ -1047,7 +1063,7 @@ async function example() { | displayName | string | 是 | 是 | 显示文件名，包含后缀名。 | | title | string | 是 | 是 | 文件标题。 | | relativePath8+ | string | 是 | 是 | 相对公共目录路径。 | -| parent8+ | number | 是 | 否 | 父目录id。 | +| parent8+ | number | 是 | 否 | 父目录id。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为0。 | | size | number | 是 | 否 | 文件大小（单位：字节）。 | | dateAdded | number | 是 | 否 | 添加日期（添加文件时间到1970年1月1日的秒数值）。 | | dateModified | number | 是 | 否 | 修改日期（修改文件时间到1970年1月1日的秒数值，修改文件名不会改变此值，当文件内容发生修改时才会更新）。| @@ -1058,9 +1074,9 @@ async function example() { | height | number | 是 | 否 | 图片高度（单位：像素）。 | | orientation | number | 是 | 是 | 图片显示方向（顺时针旋转角度，如0，90，180 单位：度）。 | | duration8+ | number | 是 | 否 | 持续时间（单位：毫秒）。 | -| albumId | number | 是 | 否 | 文件所归属的相册编号。 | -| albumUri8+ | string | 是 | 否 | 文件所归属相册uri。 | -| albumName | string | 是 | 否 | 文件所归属相册名称。 | +| albumId | number | 是 | 否 | 文件所归属的相册编号。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为0。 | +| albumUri8+ | string | 是 | 否 | 文件所归属相册uri。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为空字符串。 | +| albumName | string | 是 | 否 | 文件所归属相册名称。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为空字符串。 | ### isDirectory8+ @@ -1146,6 +1162,9 @@ commitModify(callback: AsyncCallback<void>): void 修改文件的元数据，使用callback方式返回异步结果。 +> **说明：** +> 由于API version 10的SDK上audio没有orientation属性，在使用commitModify接口时将无法对audio资源的orientation属性进行修改。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core @@ -1183,6 +1202,9 @@ commitModify(): Promise<void> 修改文件的元数据，使用promise方式返回异步结果。 +> **说明：** +> 由于API version 10的SDK上audio没有orientation属性，在使用commitModify接口时将无法对audio资源的orientation属性进行修改。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**：SystemCapability.Multimedia.MediaLibrary.Core diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md new file mode 100644 index 0000000000000000000000000000000000000000..468d7c3461f1920d9dcf6f6f23805ac694b9214a --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md @@ -0,0 +1,145 @@ +# 文件子系统ChangeLog + +## cl.file.1 mediaLibrary相关接口兼容性变更 + +mediaLibrary部分接口兼容性变更。 + +**变更影响** + +[mediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md)部分接口兼容性变更。 +基于此前版本开发的应用，需注意接口的迭代更新。 + +**关键接口/组件变更** + +| 模块名 | 方法/属性/枚举/常量 | 变更类型 | +| ------------------------- | ------------------------------------------------------------ | -------- | +| medialibrary | **function** getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void | 接口兼容性变更 | +| medialibrary | **function** getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> | 接口兼容性变更 | +| medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void| 接口兼容性变更 | +| medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset>| 接口兼容性变更 | +| medialibrary | **function** getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album>>): void | 接口兼容性变更 | +| medialibrary | **function** getAlbums(options: MediaFetchOptions): Promise<Array<Album>> | 接口兼容性变更 | +| medialibrary | **function** FileAsset.commitModify(callback: AsyncCallback<void>): void | 接口兼容性变更 | +| medialibrary | **function** FileAsset.commitModify(): Promise<void> | 接口兼容性变更 | + +**适配指导** + +**getFileAssets接口获取文件资源兼容性影响：** + +在API version 10上，摒弃了物理目录作为相册的设计，采用了逻辑相册的设计，一个相册中可以添加多个文件，一个文件也可以在多个相册中呈现。新的设计将带来parent、albumId、albumUri和albumName属性使用上的不兼容，无法作为MediaFetchOptions的参数在getFileAssets接口中使用。下面示例代码为错误示例： + +1. 使用[getMediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary)接口获取媒体库实例。 +2. 创建检索条件[MediaFetchOptions](../../../application-dev/reference/apis/js-apis-medialibrary.md#mediafetchoptions7)。 +3. 调用[getFileAssets](../../../application-dev/reference/apis/js-apis-medialibrary.md#getfileassets7)接口获取文件资源。 + +**错误示例：** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey; + let albumId = 1; + let getImageOp = { + selections: fileKeyObj.ALBUM_ID + '= ?', // 使用parent、albumId、albumUri和albumName属性查询均无法获取文件资源。 + selectionArgs: [albumId.toString()], + }; + const fetchFileResult = await media.getFileAssets(getImageOp); // 查询失败，获取的fetchFileResult为空。 + const fileAsset = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +推荐使用以下方式调用getFileAssets接口获取文件资源： + +**正确示例：** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey; + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], // 查询所有图片类型的文件。 + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const fileAsset = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +**createAsset接口创建相册兼容性影响：** + +由于API version 10的SDK上relativePath和相册没有关联关系，文件创建成功后，relativePath的最后一级目录不会作为相册呈现。 + +**getAlbums接口获取相册兼容性影响：** + +由于API version 10的SDK上relativePath和相册没有关联关系，在使用getAlbums时不支持relativePath作为查询条件，并且ALBUM_NAME参数只能使用"Camera"和"Screenshots"。下面示例代码为错误示例： + +1. 使用[getMediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary)接口获取媒体库实例。 +2. 创建相册检索条件[MediaFetchOptions](../../../application-dev/reference/apis/js-apis-medialibrary.md#mediafetchoptions7)。 +3. 调用[getAlbums](../../../application-dev/reference/apis/js-apis-medialibrary.md#getalbums7)接口获取相册。 + +**错误示例：** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let AlbumNoArgsfetchOp = { + selections: mediaLibrary.FileKey.ALBUM_NAME + ' = ?', + selectionArgs: ['新建相册1'], // 获取albumName为新建相册1的相册。 + }; + const fetchFileResult = await media.getAlbums(AlbumNoArgsfetchOp); // 查询失败，获取的fetchFileResult为空。 + const album = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary album albumName: ' + album.albumName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +使用如下示例代码可以获取Camera和Screenshots相册。 + +**正确示例：** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let AlbumNoArgsfetchOp = { + selections: mediaLibrary.FileKey.ALBUM_NAME + ' = ? OR ' + mediaLibrary.FileKey.ALBUM_NAME + ' = ?', + selectionArgs: ['Camera', 'Screenshots'], // 获取相机相册和截屏录屏相册。 + }; + const fetchFileResult = await media.getAlbums(AlbumNoArgsfetchOp); + const album = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary album albumName: ' + album.albumName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +**FileAsset.commitModify接口获取相册兼容性影响：** + +在API version 10的SDK上去掉了针对audio无意义的orientation属性，在使用commitModify接口时将无法对audio资源的orientation属性进行修改。