!20613 mediaLibrary compatibility change

Merge pull request !20613 from 胡伟奇/changelog

!20613 mediaLibrary compatibility change
Merge pull request !20613 from 胡伟奇/changelog
86c07bb1 · openharmony_ci · Gitee · 52a3a6dc · 723f67ae · 86c07bb1
2 changed file
--- 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&lt;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&lt;FetchFileResult&gt;

 获取文件资源，使用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&lt;Array&lt;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&lt;Array&lt;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&lt;Array&lt;Album&gt;&gt;

 获取相册列表，使用 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&lt;Array&lt;Album&gt;&gt;

 ```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                   | 是   | 是   | 文件标题。                                               |
 | relativePath<sup>8+</sup> | string                   | 是   | 是   | 相对公共目录路径。                                       |
-| parent<sup>8+</sup>       | number                   | 是   | 否   | 父目录id。                                               |
+| parent<sup>8+</sup>       | 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  单位：度）。 |
 | duration<sup>8+</sup>     | number                   | 是   | 否   | 持续时间（单位：毫秒）。                                   |
-| albumId                   | number                   | 是   | 否   | 文件所归属的相册编号。                                   |
-| albumUri<sup>8+</sup>     | string                   | 是   | 否   | 文件所归属相册uri。                                      |
-| albumName                 | string                   | 是   | 否   | 文件所归属相册名称。                                    |
+| albumId                   | number                   | 是   | 否   | 文件所归属的相册编号。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为0。                   |
+| albumUri<sup>8+</sup>     | string                   | 是   | 否   | 文件所归属相册uri。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为空字符串。                      |
+| albumName                 | string                   | 是   | 否   | 文件所归属相册名称。由于API version 10的SDK上Asset可以存在多个相册，该属性不兼容。获取值始终为空字符串。                     |

 ### isDirectory<sup>8+</sup>

@@ -1146,6 +1162,9 @@ commitModify(callback: AsyncCallback&lt;void&gt;): 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&lt;void&gt;

 修改文件的元数据，使用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

--- 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
+# 文件子系统ChangeLog
+
+## cl.file.1 mediaLibrary相关接口兼容性变更
+
+mediaLibrary部分接口兼容性变更。
+
+**变更影响**
+
+[mediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md)部分接口兼容性变更。
+基于此前版本开发的应用，需注意接口的迭代更新。
+
+**关键接口/组件变更**
+
+| 模块名                    | 方法/属性/枚举/常量                                          | 变更类型 |
+| ------------------------- | ------------------------------------------------------------ | -------- |
+| medialibrary   |  **function** getFileAssets(options: MediaFetchOptions, callback: AsyncCallback&lt;FetchFileResult&gt;): void | 接口兼容性变更     |
+| medialibrary   |  **function** getFileAssets(options: MediaFetchOptions): Promise&lt;FetchFileResult&gt; | 接口兼容性变更     |
+| medialibrary   |  **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback&lt;FileAsset&gt;): void| 接口兼容性变更     |
+| medialibrary   |  **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise&lt;FileAsset&gt;| 接口兼容性变更     |
+| medialibrary   |  **function** getAlbums(options: MediaFetchOptions, callback: AsyncCallback&lt;Array&lt;Album&gt;&gt;): void | 接口兼容性变更     |
+| medialibrary   |  **function** getAlbums(options: MediaFetchOptions): Promise&lt;Array&lt;Album&gt;&gt; | 接口兼容性变更     |
+| medialibrary   |  **function** FileAsset.commitModify(callback: AsyncCallback&lt;void&gt;): void | 接口兼容性变更     |
+| medialibrary   |  **function** FileAsset.commitModify(): Promise&lt;void&gt; | 接口兼容性变更     |
+
+**适配指导**
+
+**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属性进行修改。