diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 0de7d46e88f8a4d568593616b1bf73bf4c44b95e..b9c27749b38281da415fb302ba660b9c09320557 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -125,6 +125,7 @@ - [@ohos.notification (Notification) (To Be Deprecated Soon)](js-apis-notification.md) - application - [EventHub](js-apis-inner-application-eventHub.md) + - Bundle Management - [@ohos.bundle.appControl (appControl)](js-apis-appControl.md) - [@ohos.bundle.bundleManager (bundleManager)](js-apis-bundleManager.md) @@ -149,6 +150,7 @@ - [permissionDef](js-apis-bundleManager-permissionDef.md) - [remoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md) - [shortcutInfo](js-apis-bundleManager-shortcutInfo.md) + - UI Page - [@ohos.animator (Animator)](js-apis-animator.md) - [@ohos.curves (Interpolation Calculation)](js-apis-curve.md) @@ -156,6 +158,7 @@ - [@ohos.mediaquery (Media Query)](js-apis-mediaquery.md) - [@ohos.promptAction (Prompt)](js-apis-promptAction.md) - [@ohos.router (Page Routing)](js-apis-router.md) + - Graphics - [@ohos.animation.windowAnimationManager (Window Animation Management)](js-apis-windowAnimationManager.md) - [@ohos.application.WindowExtensionAbility (WindowExtensionAbility)](js-apis-application-windowExtensionAbility.md) @@ -168,16 +171,19 @@ - webgl - [WebGL](js-apis-webgl.md) - [WebGL2](js-apis-webgl2.md) + - Media - [@ohos.multimedia.audio (Audio Management)](js-apis-audio.md) - [@ohos.multimedia.avsession (AVSession Management)](js-apis-avsession.md) - [@ohos.multimedia.camera (Camera Management)](js-apis-camera.md) - [@ohos.multimedia.image (Image Processing)](js-apis-image.md) - [@ohos.multimedia.media (Media)](js-apis-media.md) + - Resource Management - [@ohos.i18n (Internationalization)](js-apis-i18n.md) - [@ohos.intl (Internationalization)](js-apis-intl.md) - [@ohos.resourceManager (Resource Manager)](js-apis-resource-manager.md) + - Background Tasks - [@ohos.distributedMissionManager (Distributed Mission Management)](js-apis-distributedMissionManager.md) - [@ohos.reminderAgentManager (Reminder Agent Management)](js-apis-reminderAgentManager.md) @@ -197,6 +203,7 @@ - [@system.cipher (Cipher Algorithm)](js-apis-system-cipher.md) - security - [PermissionRequestResult](js-apis-permissionrequestresult.md) + - Data Management - [@ohos.data.dataAbility (DataAbility Predicates)](js-apis-data-ability.md) - [@ohos.data.dataShare (DataShare)](js-apis-data-dataShare.md) @@ -209,12 +216,14 @@ - [@ohos.data.ValuesBucket (Value Bucket)](js-apis-data-valuesBucket.md) - data/rdb - [resultSet (Result Set)](js-apis-data-resultset.md) + - File Management - [@ohos.file.environment (Directory Environment Capability)](js-apis-file-environment.md) - [@ohos.file.fileAccess (User File Access and Management)](js-apis-fileAccess.md) - [@ohos.file.fileExtensionInfo (User File Extension Information)](js-apis-fileExtensionInfo.md) - [@ohos.file.fs (File Management)](js-apis-file-fs.md) - [@ohos.file.hash (File Hash Processing)](js-apis-file-hash.md) + - [@ohos.file.picker (File Picker)](js-apis-file-picker.md) - [@ohos.file.securityLabel (Data Label)](js-apis-file-securityLabel.md) - [@ohos.file.statvfs (File System Space Statistics)](js-apis-file-statvfs.md) - [@ohos.file.storageStatistics (Application Storage Statistics)](js-apis-file-storage-statistics.md) @@ -230,6 +239,7 @@ - [@ohos.telephony.radio (Network Search)](js-apis-radio.md) - [@ohos.telephony.sim (SIM Management)](js-apis-sim.md) - [@ohos.telephony.sms (SMS)](js-apis-sms.md) + - Network Management - [@ohos.net.connection (Network Connection Management)](js-apis-net-connection.md) - [@ohos.net.ethernet (Ethernet Connection Management)](js-apis-net-ethernet.md) @@ -238,6 +248,7 @@ - [@ohos.net.socket (Socket Connection)](js-apis-socket.md) - [@ohos.net.webSocket (WebSocket Connection)](js-apis-webSocket.md) - [@ohos.request (Upload and Download)](js-apis-request.md) + - Connectivity - [@ohos.bluetooth (Bluetooth)](js-apis-bluetooth.md) - [@ohos.connectedTag (Active Tags)](js-apis-connectedTag.md) @@ -252,6 +263,7 @@ - tag - [nfctech (Standard NFC Technologies)](js-apis-nfctech.md) - [tagSession (Standard NFC Tag Session)](js-apis-tagSession.md) + - Basic Features - [@ohos.accessibility (Accessibility)](js-apis-accessibility.md) - [@ohos.accessibility.config (System Accessibility Configuration)](js-apis-accessibility-config.md) @@ -313,10 +325,12 @@ - [@ohos.update (Update)](js-apis-update.md) - [@ohos.usbManager (USB Management)](js-apis-usbManager.md) - [@ohos.vibrator (Vibrator)](js-apis-vibrator.md) + - Account Management - [@ohos.account.appAccount (App Account Management)](js-apis-appAccount.md) - [@ohos.account.distributedAccount (Distributed Account Management)](js-apis-distributed-account.md) - [@ohos.account.osAccount (OS Account Management)](js-apis-osAccount.md) + - Custom Management - [@ohos.configPolicy (Configuration Policy)](js-apis-configPolicy.md) - [@ohos.enterprise.adminManager (Enterprise Device Management)](js-apis-enterprise-adminManager.md) @@ -325,7 +339,7 @@ - [@ohos.enterprise.deviceInfo (Device Information Management)](js-apis-enterprise-deviceInfo.md) - [@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)](js-apis-EnterpriseAdminExtensionAbility.md) - - Language Base Class Library +- Language Base Class Library - [@ohos.buffer (Buffer)](js-apis-buffer.md) - [@ohos.convertxml (XML-to-JavaScript Conversion)](js-apis-convertxml.md) - [@ohos.process (Obtaining Process Information)](js-apis-process.md) @@ -349,9 +363,11 @@ - [@ohos.util.Vector (Linear Container Vector)](js-apis-vector.md) - [@ohos.worker (Worker Startup)](js-apis-worker.md) - [@ohos.xml (XML Parsing and Generation)](js-apis-xml.md) + - Test - [@ohos.application.testRunner (TestRunner)](js-apis-application-testRunner.md) - [@ohos.uitest (UiTest)](js-apis-uitest.md) + - APIs No Longer Maintained - [@ohos.backgroundTaskManager (Background Task Management)](js-apis-backgroundTaskManager.md) - [@ohos.bundle (Bundle)](js-apis-Bundle.md) diff --git a/en/application-dev/reference/apis/js-apis-file-picker.md b/en/application-dev/reference/apis/js-apis-file-picker.md new file mode 100644 index 0000000000000000000000000000000000000000..6b1cd7d49c140855a8e821c5b3b6f59516eb384e --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-file-picker.md @@ -0,0 +1,771 @@ +# @ohos.file.picker (File Picker) + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +**Picker** encapsulates system applications, such as **PhotoViewPicker**, **DocumentViewPicker**, and **AudioViewPicker**, and provides capabilities of selecting and saving photos, documents, and audio clips. The application can select the picker as required. + +## Modules to Import +```js +import picker from '@ohos.file.picker'; +``` + +## PhotoViewPicker + +Provides APIs for selecting and saving images and videos. Before using the APIs of **PhotoViewPicker**, you need to create a **PhotoViewPicker** instance. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Example** + +```ts +let photoPicker = new picker.PhotoViewPicker(); +``` + +### select + +select(option?: PhotoSelectOptions) : Promise<PhotoSelectResult> + +Selects one or more images or videos in a **photoPicker** page. This API uses a promise to return the result. You can pass in **PhotoSelectOptions** to specify the media type and the maximum number of files to select. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [PhotoSelectOptions](#photoselectoptions) | No | Options for selecting images or videos.| + +**Return value** + +| Type | Description | +| ----------------------------- | :---- | +| [PhotoSelectResult](#photoselectresult) | Promise used to return information about the images or videos selected.| + +**Example** + +```ts +async function example() { + try { + let PhotoSelectOptions = new picker.PhotoSelectOptions(); + PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE; + PhotoSelectOptions.maxSelectNumber = 5; + let photoPicker = new picker.PhotoViewPicker(); + photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult) => { + console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); + }).catch((err) => { + console.error('PhotoViewPicker.select failed with err: ' + err); + }); + } catch (err) { + console.error('PhotoViewPicker failed with err: ' + err); + } +} +``` + +### select + +select(option: PhotoSelectOptions, callback: AsyncCallback<PhotoSelectResult>) : void + +Selects one or more images or videos in a **photoPicker** page. This API uses an asynchronous callback to return the result. You can pass in **PhotoSelectOptions** to specify the media type and the maximum number of files to select. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [PhotoSelectOptions](#photoselectoptions) | Yes | Options for selecting images or videos.| +| callback | AsyncCallback<[PhotoSelectResult](#photoselectresult)> | Yes | Callback invoked to return information about the images or videos selected.| + +**Example** + +```ts +async function example() { + try { + let PhotoSelectOptions = new picker.PhotoSelectOptions(); + PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE; + PhotoSelectOptions.maxSelectNumber = 5; + let photoPicker = new picker.PhotoViewPicker(); + photoPicker.select(PhotoSelectOptions, (err, PhotoSelectResult) => { + if (err) { + console.error('PhotoViewPicker.select failed with err: ' + err); + return; + } + console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); + }); + } catch (err) { + console.error('PhotoViewPicker failed with err: ' + err); + } +} +``` + +### select + +select(callback: AsyncCallback<PhotoSelectResult>) : void + +Selects one or more images or videos in a **photoPicker** page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| callback | AsyncCallback<[PhotoSelectResult](#photoselectresult)> | Yes | Callback invoked to return information about the images or videos selected.| + +**Example** + +```ts +async function example() { + try { + let photoPicker = new picker.PhotoViewPicker(); + photoPicker.select((err, PhotoSelectResult) => { + if (err) { + console.error('PhotoViewPicker.select failed with err: ' + err); + return; + } + console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); + }); + } catch (err) { + console.error('PhotoViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(option?: PhotoSaveOptions) : Promise<Array<string>> + +Saves one or more images or videos in a **photoPicker** page. This API uses a promise to return the result. You can pass in **PhotoSaveOptions** to specify the file names of the images or videos to save. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [PhotoSaveOptions](#photosaveoptions) | No | Options for saving images or videos.| + +**Return value** + +| Type | Description | +| ----------------------------- | :---- | +| <Array<string>> | Promise used to return the URIs of the files saved.| + +**Example** + +```ts +async function example() { + try { + let PhotoSaveOptions = new picker.PhotoSaveOptions(); + PhotoSaveOptions.newFileNames = ['PhotoViewPicker01.jpg', 'PhotoViewPicker01.mp4']; + let photoPicker = new picker.PhotoViewPicker(); + photoPicker.save(PhotoSaveOptions).then((PhotoSaveResult) => { + console.info('PhotoViewPicker.save successfully, PhotoSaveResult uri: ' + JSON.stringify(PhotoSaveResult)); + }).catch((err) => { + console.error('PhotoViewPicker.save failed with err: ' + err); + }); + } catch (err) { + console.error('PhotoViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(option: PhotoSaveOptions, callback: AsyncCallback<Array<string>>) : void + +Saves one or more images or videos in a **photoPicker** page. This API uses an asynchronous callback to return the result. You can pass in **PhotoSaveOptions** to specify the file names of the images or videos to save. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [PhotoSaveOptions](#photosaveoptions) | Yes | Options for saving images or videos.| +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the files saved.| + +**Example** + +```ts +async function example() { + try { + let PhotoSaveOptions = new picker.PhotoSaveOptions(); + PhotoSaveOptions.newFileNames = ['PhotoViewPicker02.jpg','PhotoViewPicker02.mp4']; + let photoPicker = new picker.PhotoViewPicker(); + photoPicker.save(PhotoSaveOptions, (err, PhotoSaveResult) => { + if (err) { + console.error('PhotoViewPicker.save failed with err: ' + err); + return; + } + console.info('PhotoViewPicker.save successfully, PhotoSaveResult uri: ' + JSON.stringify(PhotoSaveResult)); + }); + } catch (err) { + console.error('PhotoViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(callback: AsyncCallback<Array<string>>) : void + +Saves one or more images or videos in a **photoPicker** page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the files saved.| + +**Example** + +```ts +async function example() { + try { + let photoPicker = new picker.PhotoViewPicker(); + photoPicker.save((err, PhotoSaveResult) => { + if (err) { + console.error('PhotoViewPicker.save failed with err: ' + err); + return; + } + console.info('PhotoViewPicker.save successfully, PhotoSaveResult uri: ' + JSON.stringify(PhotoSaveResult)); + }); + } catch (err) { + console.error('PhotoViewPicker failed with err: ' + err); + } +} +``` + +## DocumentViewPicker + +Provides APIs for selecting and saving non-media files, for example, documents in a variety of formats. Before using the APIs of **DocumentViewPicker**, you need to create a **DocumentViewPicker** instance. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Example** + +```ts +let documentPicker = new picker.DocumentViewPicker(); +``` + +### select + +select(option?: DocumentSelectOptions) : Promise<Array<string>> + +Selects one or more documents in a **documentPicker** page. This API uses a promise to return the result. You can pass in **DocumentSelectOptions**. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [DocumentSelectOptions](#documentselectoptions) | No | Options for selecting documents.| + +**Return value** + +| Type | Description | +| ----------------------------- | :---- | +| <Array<string>> | Promise used to return the URIs of the documents selected.| + +**Example** + +```ts +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)); + }).catch((err) => { + console.error('DocumentViewPicker.select failed with err: ' + err); + }); + } catch (err) { + console.error('DocumentViewPicker failed with err: ' + err); + } +} +``` + +### select + +select(option: DocumentSelectOptions, callback: AsyncCallback<Array<string>>) : void + +Selects one or more documents in a **documentPicker** page. This API uses an asynchronous callback to return the result. You can pass in **DocumentSelectOptions**. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [DocumentSelectOptions](#documentselectoptions) | Yes | Options for selecting documents.| +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents selected.| + +**Example** + +```ts +async function example() { + try { + let DocumentSelectOptions = new picker.DocumentSelectOptions(); + let documentPicker = new picker.DocumentViewPicker(); + documentPicker.select(DocumentSelectOptions, (err, DocumentSelectResult) => { + if (err) { + console.error('DocumentViewPicker.select failed with err: ' + err); + return; + } + console.info('DocumentViewPicker.select successfully, DocumentSelectResult uri: ' + JSON.stringify(DocumentSelectResult)); + }); + } catch (err) { + console.error('DocumentViewPicker failed with err: ' + err); + } +} +``` + +### select + +select(callback: AsyncCallback<Array<string>>) : void + +Selects one or more documents in a **documentPicker** page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents selected.| + +**Example** + +```ts +async function example() { + try { + let documentPicker = new picker.DocumentViewPicker(); + documentPicker.select((err, DocumentSelectResult) => { + if (err) { + console.error('DocumentViewPicker.select failed with err: ' + err); + return; + } + console.info('DocumentViewPicker.select successfully, DocumentSelectResult uri: ' + JSON.stringify(DocumentSelectResult)); + }); + } catch (err) { + console.error('DocumentViewPicker failed with err: ' + err); + } +} +``` + + +### save + +save(option?: DocumentSaveOptions) : Promise<Array<string>> + +Saves one or more documents in a **documentPicker** page. This API uses a promise to return the result. You can pass in **DocumentSaveOptions** to specify the file names to save. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [DocumentSaveOptions](#documentsaveoptions) | No | Options for saving the documents.| + +**Return value** + +| Type | Description | +| ----------------------------- | :---- | +| <Array<string>> | Promise used to return the URIs of the documents saved.| + +**Example** + +```ts +async function example() { + 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)); + }).catch((err) => { + console.error('DocumentViewPicker.save failed with err: ' + err); + }); + } catch (err) { + console.errort('DocumentViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(option: DocumentSaveOptions, callback: AsyncCallback<Array<string>>) : void + +Saves one or more documents in a **documentPicker** page. This API uses an asynchronous callback to return the result. You can pass in **DocumentSaveOptions** to specify the file names to save. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [DocumentSaveOptions](#documentsaveoptions) | Yes | Options for saving the documents.| +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents saved.| + +**Example** + +```ts +async function example() { + try { + let DocumentSaveOptions = new picker.DocumentSaveOptions(); + DocumentSaveOptions.newFileNames = ['DocumentViewPicker02.txt']; + let documentPicker = new picker.DocumentViewPicker(); + documentPicker.save(DocumentSaveOptions, (err, DocumentSaveResult) => { + if (err) { + console.error('DocumentViewPicker.save failed with err: ' + err); + return; + } + console.info('DocumentViewPicker.save successfully, DocumentSaveResult uri: ' + JSON.stringify(DocumentSaveResult)); + }); + } catch (err) { + console.errort('DocumentViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(callback: AsyncCallback<Array<string>>) : void + +Saves one or more documents in a **documentPicker** page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents saved.| + +**Example** + +```ts +async function example() { + try { + let documentPicker = new picker.DocumentViewPicker(); + documentPicker.save((err, DocumentSaveResult) => { + if (err) { + console.error('DocumentViewPicker.save failed with err: ' + err); + return; + } + console.info('DocumentViewPicker.save successfully, DocumentSaveResult uri: ' + JSON.stringify(DocumentSaveResult)); + }); + } catch (err) { + console.errort('DocumentViewPicker failed with err: ' + err); + } +} +``` + +## AudioViewPicker + +Provides APIs for selecting and saving audio files. Before using the APIs of **AudioViewPicker**, you need to create an **AudioViewPicker** instance. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Example** + +```ts +let audioPicker = new picker.AudioViewPicker(); +``` + +### select + +select(option?: AudioSelectOptions) : Promise<Array<string>> + +Selects one or more audio files in an **audioPicker** page (currently, a **documentPicker** page is displayed). This API uses a promise to return the result. You can pass in **AudioSelectOptions**. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [AudioSelectOptions](#audioselectoptions) | No | Options for selecting audio files.| + +**Return value** + +| Type | Description | +| ----------------------------- | :---- | +| <Array<string>> | Promise used to return the URIs of the audio files selected.| + +**Example** + +```ts +async function example() { + try { + let AudioSelectOptions = new picker.AudioSelectOptions(); + let audioPicker = new picker.AudioViewPicker(); + audioPicker.select(AudioSelectOptions).then((AudioSelectResult) => { + console.info('AudioViewPicker.select successfully, AudioSelectResult uri: ' + JSON.stringify(AudioSelectResult)); + }).catch((err) => { + console.error('AudioViewPicker.select failed with err: ' + err); + }); + } catch (err) { + console.error('AudioViewPicker failed with err: ' + err); + } +} +``` + +### select + +select(option: AudioSelectOptions, callback: AsyncCallback<Array<string>>) : void + +Selects one or more audio files in an **audioPicker** page (currently, a **documentPicker** page is displayed). This API uses an asynchronous callback to return the result. You can pass in **AudioSelectOptions**. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [AudioSelectOptions](#audioselectoptions) | Yes | Options for selecting audio files.| +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio files selected.| + +**Example** + +```ts +async function example() { + try { + let AudioSelectOptions = new picker.AudioSelectOptions(); + let audioPicker = new picker.AudioViewPicker(); + audioPicker.select(AudioSelectOptions, (err, AudioSelectResult) => { + if (err) { + console.error('AudioViewPicker.select failed with err: ' + err); + return; + } + console.info('AudioViewPicker.select successfully, AudioSelectResult uri: ' + JSON.stringify(AudioSelectResult)); + }); + } catch (err) { + console.error('AudioViewPicker failed with err: ' + err); + } +} +``` + +### select + +select(callback: AsyncCallback<Array<string>>) : void + +Selects one or more audio files in an **audioPicker** page (currently, a **documentPicker** page is displayed). This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio files selected.| + +**Example** + +```ts +async function example() { + try { + let audioPicker = new picker.AudioViewPicker(); + audioPicker.select((err, AudioSelectResult) => { + if (err) { + console.error('AudioViewPicker.select failed with err: ' + err); + return; + } + console.info('AudioViewPicker.select successfully, AudioSelectResult uri: ' + JSON.stringify(AudioSelectResult)); + }); + } catch (err) { + console.error('AudioViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(option?: AudioSaveOptions) : Promise<Array<string>> + +Saves one or more audio files in an **audioPicker** page (currently, a **documentPicker** page is displayed). This API uses a promise to return the result. You can pass in **AudioSaveOptions** to specify the file names of the audio clips to save. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [AudioSaveOptions](#audiosaveoptions) | No | Options for saving audio files.| + +**Return value** + +| Type | Description | +| ----------------------------- | ---- | +| <Array<string>> | Promise used to return the URIs of the audio files saved.| + +**Example** + +```ts +async function example() { + try { + let AudioSaveOptions = new picker.AudioSaveOptions(); + AudioSaveOptions.newFileNames = ['AudioViewPicker01.mp3']; + let audioPicker = new picker.AudioViewPicker(); + audioPicker.save(AudioSaveOptions).then((AudioSaveResult) => { + console.info('AudioViewPicker.save successfully, AudioSaveResult uri: ' + JSON.stringify(AudioSaveResult)) + }).catch((err) => { + console.error('AudioViewPicker.save failed with err: ' + err); + }); + } catch (err) { + console.error('AudioViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(option: AudioSaveOptions, callback: AsyncCallback<Array<string>>) : void + +Saves one or more audio files in an **audioPicker** page (currently, a **documentPicker** page is displayed). This API uses an asynchronous callback to return the result. You can pass in **AudioSaveOptions** to specify the file names of the audio clips to save. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| option | [AudioSaveOptions](#audiosaveoptions) | Yes | Options for saving audio files.| +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio files saved.| + +**Example** + +```ts +async function example() { + try { + let AudioSaveOptions = new picker.AudioSaveOptions(); + AudioSaveOptions.newFileNames = ['AudioViewPicker02.mp3']; + let audioPicker = new picker.AudioViewPicker(); + audioPicker.save(AudioSaveOptions, (err, AudioSaveResult) => { + if (err) { + console.error('AudioViewPicker.save failed with err: ' + err); + return; + } + console.info('AudioViewPicker.save successfully, AudioSaveResult uri: ' + JSON.stringify(AudioSaveResult)); + }); + } catch (err) { + console.error('AudioViewPicker failed with err: ' + err); + } +} +``` + +### save + +save(callback: AsyncCallback<Array<string>>) : void + +Saves one or more audio files in an **audioPicker** page (currently, a **documentPicker** page is displayed). This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | -------------------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio files saved.| + +**Example** + +```ts +async function example() { + try { + let audioPicker = new picker.AudioViewPicker(); + audioPicker.save((err, AudioSaveResult) => { + if (err) { + console.error('AudioViewPicker.save failed with err: ' + err); + return; + } + console.info('AudioViewPicker.save successfully, AudioSaveResult uri: ' + JSON.stringify(AudioSaveResult)); + }); + } catch (err) { + console.error('AudioViewPicker failed with err: ' + err); + } +} +``` + +## PhotoViewMIMETypes + +Enumerates the media file types that can be selected. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Value| Description| +| ----- | ---- | ---- | +| IMAGE_TYPE | 'image/*' | Image.| +| VIDEO_TYPE | 'video/*' | Video.| +| IMAGE_VIDEO_TYPE | '\*/*' | Image and video.| + +## PhotoSelectOptions + +Defines the options for selecting images or videos. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------- | ---- | -------------------------------- | +| MIMEType? | [PhotoViewMIMETypes](#photoviewmimetypes) | No | Media file types to select.| +| maxSelectNumber? | number | No | Maximum number of media files to select. The default value is **50**, and the maximum value is **500**. | + +## PhotoSelectResult + +Defines information about the images or videos selected. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ------------------- | ---- | ---- | ------------------------------ | +| photoUris | Array<string> | Yes | Yes | URIs of the media files selected.| +| isOriginalPhoto | boolean | Yes | Yes | Whether the selected media file is the original image.| + +## PhotoSaveOptions + +Defines the options for saving images or videos. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------- | ---- | ---------------------------- | +| newFileNames? | Array<string> | No | Files names of the images or videos to save.| + +## DocumentSelectOptions + +Defines the options for selecting documents. Currently, this parameter cannot be configured. + +**System capability**: SystemCapability.FileManagement.UserFileService + +## DocumentSaveOptions + +Defines the options for saving documents. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------- | ---- | ---------------------------- | +| newFileNames? | Array<string> | No | File names of the documents to save.| + +## AudioSelectOptions + +Defines the options for selecting audio clips. Currently, this parameter cannot be configured. + +**System capability**: SystemCapability.FileManagement.UserFileService + +## AudioSaveOptions + +Defines the options for saving audio files. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------- | ---- | ---------------------------- | +| newFileNames? | Array<string> | No | File names of the audio clips to save.| diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index 1b60c450840997a0834a1bb6635a747b8f7f6a47..852a1aa400589a24f15b2d6bb4d72253ba2ea3d9 100755 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -239,6 +239,7 @@ - [@ohos.file.fileExtensionInfo (公共文件访问与管理属性信息)](js-apis-fileExtensionInfo.md) - [@ohos.file.fs (文件管理)](js-apis-file-fs.md) - [@ohos.file.hash (文件哈希处理)](js-apis-file-hash.md) + - [@ohos.file.picker (选择器)](js-apis-file-picker.md) - [@ohos.file.securityLabel (数据标签)](js-apis-file-securityLabel.md) - [@ohos.file.statvfs (文件系统空间统计)](js-apis-file-statvfs.md) - [@ohos.file.storageStatistics (应用空间统计)](js-apis-file-storage-statistics.md)