From c9607399bc2ef459ddf1bc708dd2e8b225f7539f Mon Sep 17 00:00:00 2001 From: Gloria Date: Fri, 2 Jun 2023 14:47:03 +0800 Subject: [PATCH] Update docs against 18467 Signed-off-by: wusongqing --- .../v3.2-beta5/changelogs-mediaLibrary.md | 280 ++++++++++++++---- 1 file changed, 218 insertions(+), 62 deletions(-) diff --git a/en/release-notes/changelogs/v3.2-beta5/changelogs-mediaLibrary.md b/en/release-notes/changelogs/v3.2-beta5/changelogs-mediaLibrary.md index 459adbacf8..b3e49188e7 100644 --- a/en/release-notes/changelogs/v3.2-beta5/changelogs-mediaLibrary.md +++ b/en/release-notes/changelogs/v3.2-beta5/changelogs-mediaLibrary.md @@ -1,64 +1,33 @@ -# File Management Subsystem Changelog +# File Subsystem Changelog ## cl.file.1 mediaLibrary APIs Changed -The **MediaLibrary** class of the multimedia component is replaced by the **FilePicker** class. +All APIs provided by the mediaLibrary module of the multimedia subsystem are deprecated. **Change Impact** -For applications developed based on earlier versions, pay attention to the changes of APIs. **FilePicker** is a system application preset in OpenHarmony. You can use it to select and save files. +All APIs described in [mediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md) are deprecated. Third-party applications can only select and save files in the public directory by calling the APIs of [FilePicker](../../../application-dev/reference/apis/js-apis-file-picker.md). +For applications developed based on earlier versions, pay attention to the changes of APIs. **Key API/Component Changes** -The APIs of **MediaLibrary**, located in **@ohos.multimedia.medialibrary**, are deprecated. The **FilePicker** class, located in [@ohos.file.picker](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.file.picker.d.ts) is used. +The table below lists the **mediaLibrary** APIs that can be substituted by the **FilePicker** APIs. | Module | Method/Attribute/Enum/Constant | Change Type| | ------------------------- | ------------------------------------------------------------ | -------- | -| medialibrary | **function** getMediaLibrary(): MediaLibrary; | Deprecated | | medialibrary | **function** getMediaLibrary(context: Context): MediaLibrary; | Deprecated | | medialibrary | **function** getFileAssets(options: MediaFetchOptions, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** getFileAssets(options: MediaFetchOptions): Promise\ | Deprecated | -| medialibrary | **function** on(type: 'deviceChange'\|'albumChange'\|'imageChange'\|'audioChange'\|'videoChange'\|'fileChange'\|'remoteFileChange', callback: Callback\): void | Deprecated | -| medialibrary | **function** off(type: 'deviceChange'\|'albumChange'\|'imageChange'\|'audioChange'\|'videoChange'\|'fileChange'\|'remoteFileChange', callback?: Callback\): void | Deprecated | | medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise\ | Deprecated | -| medialibrary | **function** deleteAsset(uri: string): Promise\ | Deprecated | -| medialibrary | **function** deleteAsset(uri: string, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** getPublicDirectory(type: DirectoryType, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** getPublicDirectory(type: DirectoryType): Promise\ | Deprecated | -| medialibrary | **function** getAlbums(options: MediaFetchOptions, callback: AsyncCallback\\>): void | Deprecated | -| medialibrary | **function** getAlbums(options: MediaFetchOptions): Promise\\> | Deprecated | -| medialibrary | **function** release(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** release(callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** release(): Promise\ | Deprecated | -| medialibrary | **function** storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** storeMediaAsset(option: MediaAssetOption): Promise\ | Deprecated | -| medialibrary | **function** startImagePreview(images: Array\, index: number, callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** startImagePreview(images: Array\, callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** startImagePreview(images: Array\, index?: number): Promise\ | Deprecated | -| medialibrary | **function** startMediaSelect(option: MediaSelectOption, callback: AsyncCallback\\>): void | Deprecated | -| medialibrary | **function** startMediaSelect(option: MediaSelectOption): Promise\\> | Deprecated | -| medialibrary | **function** getActivePeers(): Promise\\>; | Deprecated | -| medialibrary | **function** getActivePeers(callback: AsyncCallback\\>): void; | Deprecated | -| medialibrary | **function** getAllPeers(): Promise\\>; | Deprecated | -| medialibrary | **function** FileAsset.isDirectory(callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.isDirectory():Promise\ | Deprecated | -| medialibrary | **function** FileAsset.commitModify(callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.commitModify(): Promise\ | Deprecated | | medialibrary | **function** FileAsset.open(mode: string, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** FileAsset.open(mode: string): Promise\ | Deprecated | | medialibrary | **function** FileAsset.close(fd: number, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** FileAsset.close(fd: number): Promise\ | Deprecated | -| medialibrary | **function** FileAsset.getThumbnail(callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.getThumbnail(size: Size, callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.getThumbnail(size?: Size): Promise\ | Deprecated | -| medialibrary | **function** FileAsset.favorite(isFavorite: boolean, callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.favorite(isFavorite: boolean): Promise\ | Deprecated | -| medialibrary | **function** FileAsset.isFavorite(callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.isFavorite():Promise\ | Deprecated | -| medialibrary | **function** FileAsset.trash(isTrash: boolean, callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.trash(isTrash: boolean): Promise\ | Deprecated | -| medialibrary | **function** FileAsset.isTrash(callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** FileAsset.isTrash():Promise\ | Deprecated | | medialibrary | **function** FetchFileResult.getCount(): number | Deprecated | | medialibrary | **function** FetchFileResult.isAfterLast(): boolean | Deprecated | | medialibrary | **function** FetchFileResult.close(): void | Deprecated | @@ -72,45 +41,232 @@ The APIs of **MediaLibrary**, located in **@ohos.multimedia.medialibrary**, are | medialibrary | **function** FetchFileResult.getPositionObject(index: number): Promise\ | Deprecated | | medialibrary | **function** FetchFileResult.getAllObject(callback: AsyncCallback\\>): void | Deprecated | | medialibrary | **function** FetchFileResult.getAllObject(): Promise\\> | Deprecated | -| medialibrary | **function** Album.commitModify(callback: AsyncCallback\): void | Deprecated | -| medialibrary | **function** Album.commitModify(): Promise\ | Deprecated | | medialibrary | **function** Album.getFileAssets(options: MediaFetchOptions, callback: AsyncCallback\): void | Deprecated | | medialibrary | **function** Album.getFileAssets(options?: MediaFetchOptions): Promise\ | Deprecated | -| medialibrary | **enum** DeviceType | Deprecated | | medialibrary | **enum** FileKey | Deprecated | | medialibrary | **enum** DirectoryType | Deprecated | | medialibrary | **enum** MediaType | Deprecated | -| medialibrary | **interface** PeerInfo | Deprecated | -| medialibrary | **interface** Size | Deprecated | | medialibrary | **interface** MediaFetchOptions | Deprecated | -| medialibrary | **interface** MediaAssetOption | Deprecated | -| medialibrary | **interface** MediaSelectOption | Deprecated | | medialibrary | **interface** FileAsset | Deprecated | **Adaptation Guide** -For example, refer to the code snippet below to call an API to select an image: +**The following example shows how to use the mediaLibrary APIs to edit a file in the public directory:** + +1. Call **getMediaLibrary** to obtain a **mediaLibrary** instance. +2. Create a **MediaFetchOptions** object, and call **getFileAssets** to obtain files in the public directory. +3. Call the **FetchFileResult** APIs to obtain the file asset of the target file. +4. Call **fileAsset.open** to open the file and obtain the FD. +5. Call [fs.writeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#writesync) to edit the file through the FD. +6. After the edit, call **fileAsset.close** to close the FD of the file. +7. Call **fetchFileResult.close** to release the resources occupied by **getFileAssets**. +8. Call **release** to release the **mediaLibrary** instance. + +**Example** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; +import fs from '@ohos.file.fs'; + +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()], + order: fileKeyObj.DATE_ADDED + ' DESC', + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const fileAsset = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); + let fd = await fileAsset.open('rw'); + console.info('mediaLibrary fileAsset open fd: ' + fd); + let writeLen = fs.writeSync(fd, 'hello, world'); + console.info('write data to file succeed and size is: ' + writeLen); + fileAsset.close(fd); + fetchFileResult.close(); + media.release(); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +**The following example shows how to use the FilePicker APIs to edit a file in the public directory:** + +1. Obtain a **DocumentViewPicker** object. +2. Call **DocumentViewPicker.select** to select a file. +3. After a file is selected, a file URI is returned. +4. After the UI is returned from DocumentViewPicker, call [fs.openSync](../../../application-dev/reference/apis/js-apis-file-fs.md#fsopensync) to open the file based on the URI and obtain the FD. +5. Call [fs.writeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#writesync) to edit the file through the FD. +6. After the edit, call [fs.closeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#closesync) to close the FD. + +**Example** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; +import picker from '@ohos.file.picker'; +import fs from '@ohos.file.fs'; + +let uri; + +async function example() { + try { + let DocumentSelectOptions = new picker.DocumentSelectOptions(); + let documentPicker = new picker.DocumentViewPicker(); + documentPicker.select(DocumentSelectOptions).then((DocumentSelectResult) => { + console.info('DocumentViewPicker.select successfully, DocumentSelectResult uri: ' + JSON.stringify(DocumentSelectResult)); + uri = DocumentSelectResult[0]; + }).catch((err) => { + console.error('DocumentViewPicker.select failed with err: ' + err); + }); + } catch (err) { + console.error('DocumentViewPicker failed with err: ' + err); + } +} + +async function writeFile() { + try { + let file = fs.openSync(uri, fs.OpenMode.READ_WRITE); + console.info('DocumentViewPicker file fd: ' + file.fd); + let writeLen = fs.writeSync(file.fd, 'hello, world'); + console.info('write data to file succeed and size is: ' + writeLen); + fs.closeSync(file); + } catch (err) { + console.error('DocumentViewPicker fail, err: ' + err); + } +} +``` + +**The following example shows how to use the mediaLibrary APIs to create a file in the public directory:** + +1. Call **getMediaLibrary** to obtain a **mediaLibrary** instance. +2. Call **getPublicDirectory** to obtain the path of the public directory. +3. Call **createAsset** to create a file and obtain the file asset. +4. Call **fileAsset.open** to open the file and obtain the FD. +5. Call **fs.write** to edit the file through the FD. +6. After the edit, call **fileAsset.close** to close the FD. +7. Call **release** to release the **mediaLibrary** instance. + +**Example** ```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; +import fs from '@ohos.file.fs'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getMediaLibrary(context); + let mediaType = mediaLibrary.MediaType.FILE; + let DIR_DOWNLOAD = mediaLibrary.DirectoryType.DIR_DOWNLOAD; + const path = await media.getPublicDirectory(DIR_DOWNLOAD); + const fileAsset = await media.createAsset(mediaType, 'test.txt', path); + console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); + let fd = await fileAsset.open('rw'); + console.info('mediaLibrary fileAsset open fd: ' + fd); + let writeLen = fs.writeSync(fd, 'hello, world'); + console.info('write data to file succeed and size is: ' + writeLen); + fileAsset.close(fd); + media.release(); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +**The following example shows how to use the FilePicker APIs to create a file in the public directory:** + +1. Obtain a **DocumentViewPicker** object. +2. Call **DocumentViewPicker.save** to create and save an empty file. +3. After the file is saved, a file URI is returned. +4. After the UI is returned from DocumentViewPicker, call [fs.openSync](../../../application-dev/reference/apis/js-apis-file-fs.md#fsopensync) to open the file based on the URI and obtain the FD. +5. Call [fs.writeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#writesync) to edit the file through the FD. +6. After the edit, call [fs.closeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#closesync) to close the FD. + +**Example** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; import picker from '@ohos.file.picker'; +import fs from '@ohos.file.fs'; + +let uri; async function example() { - try { - let PhotoSelectOptions = new picker.PhotoSelectOptions(); - PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE; - PhotoSelectOptions.maxSelectNumber = 1; - let photoPicker = new picker.PhotoViewPicker(); - photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult) => { - if (PhotoSelectResult !== undefined) { - console.info("PhotoViewPicker.select pass, PhotoSelectResult uri: " + JSON.stringify(PhotoSelectResult)); - } else { - console.error("PhotoViewPicker.select PhotoSelectResult is undefined"); - } - }).catch((err) => { - console.error("PhotoViewPicker.select fail, err: " + err); - }); - } catch (err) { - console.error("PhotoViewPicker fail, err: " + err); - } + try { + let DocumentSaveOptions = new picker.DocumentSaveOptions(); + DocumentSaveOptions.newFileNames = ['DocumentViewPicker01.txt']; + let documentPicker = new picker.DocumentViewPicker(); + documentPicker.save(DocumentSaveOptions).then((DocumentSaveResult) => { + console.info('DocumentViewPicker.save successfully, DocumentSaveResult uri: ' + JSON.stringify(DocumentSaveResult)); + uri = DocumentSaveResult[0]; + }).catch((err) => { + console.error('DocumentViewPicker.save failed with err: ' + err); + }); + } catch (err) { + console.error('DocumentViewPicker failed with err: ' + err); + } +} + +async function writeFile() { + try { + let file = fs.openSync(uri, fs.OpenMode.READ_WRITE); + console.info('DocumentViewPicker file fd: ' + file.fd); + let writeLen = fs.writeSync(file.fd, 'hello, world'); + console.info('write data to file succeed and size is: ' + writeLen); + fs.closeSync(file); + } catch (err) { + console.error('DocumentViewPicker fail, err: ' + err); + } } ``` + +**Key API/Component Changes** + +The table below lists the mediaLibrary APIs that are not open to third-party applications due to function control. There are no substitute APIs for them. + +| Module | Method/Attribute/Enum/Constant | Change Type| +| ------------------------- | ------------------------------------------------------------ | -------- | +| medialibrary | **function** getMediaLibrary(): MediaLibrary; | Deprecated | +| medialibrary | **function** on(type: 'deviceChange'\|'albumChange'\|'imageChange'\|'audioChange'\|'videoChange'\|'fileChange'\|'remoteFileChange', callback: Callback\): void | Deprecated | +| medialibrary | **function** off(type: 'deviceChange'\|'albumChange'\|'imageChange'\|'audioChange'\|'videoChange'\|'fileChange'\|'remoteFileChange', callback?: Callback\): void | Deprecated | +| medialibrary | **function** deleteAsset(uri: string): Promise\ | Deprecated | +| medialibrary | **function** deleteAsset(uri: string, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** storeMediaAsset(option: MediaAssetOption): Promise\ | Deprecated | +| medialibrary | **function** startImagePreview(images: Array\, index: number, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** startImagePreview(images: Array\, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** startImagePreview(images: Array\, index?: number): Promise\ | Deprecated | +| medialibrary | **function** startMediaSelect(option: MediaSelectOption, callback: AsyncCallback\\>): void | Deprecated | +| medialibrary | **function** startMediaSelect(option: MediaSelectOption): Promise\\> | Deprecated | +| medialibrary | **function** getActivePeers(): Promise\\>; | Deprecated | +| medialibrary | **function** getActivePeers(callback: AsyncCallback\\>): void; | Deprecated | +| medialibrary | **function** getAllPeers(): Promise\\>; | Deprecated | +| medialibrary | **function** FileAsset.isDirectory(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.isDirectory():Promise\ | Deprecated | +| medialibrary | **function** FileAsset.commitModify(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.commitModify(): Promise\ | Deprecated | +| medialibrary | **function** FileAsset.getThumbnail(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.getThumbnail(size: Size, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.getThumbnail(size?: Size): Promise\ | Deprecated | +| medialibrary | **function** FileAsset.favorite(isFavorite: boolean, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.favorite(isFavorite: boolean): Promise\ | Deprecated | +| medialibrary | **function** FileAsset.isFavorite(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.isFavorite():Promise\ | Deprecated | +| medialibrary | **function** FileAsset.trash(isTrash: boolean, callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.trash(isTrash: boolean): Promise\ | Deprecated | +| medialibrary | **function** FileAsset.isTrash(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** FileAsset.isTrash():Promise\ | Deprecated | +| medialibrary | **function** getAlbums(options: MediaFetchOptions, callback: AsyncCallback\\>): void | Deprecated | +| medialibrary | **function** getAlbums(options: MediaFetchOptions): Promise\\> | Deprecated | +| medialibrary | **function** Album.commitModify(callback: AsyncCallback\): void | Deprecated | +| medialibrary | **function** Album.commitModify(): Promise\ | Deprecated | +| medialibrary | **enum** DeviceType | Deprecated | +| medialibrary | **interface** PeerInfo | Deprecated | +| medialibrary | **interface** Size | Deprecated | +| medialibrary | **interface** MediaAssetOption | Deprecated | +| medialibrary | **interface** MediaSelectOption | Deprecated | -- GitLab