当前仓库属于关闭状态,部分功能使用受限,详情请查阅 仓库状态说明
1.4K Star 7.4K Fork 8.2K

OpenHarmony/docs
关闭

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
文件
克隆/下载
js-apis-file-picker.md 57.82 KB
一键复制 编辑 原始数据 按行查看 历史
dumengdi2 提交于 4个月前 . Update docs against 74122

@ohos.file.picker (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.

The picker module encapsulates APIs of PhotoViewPicker, DocumentViewPicker, and AudioViewPicker to provide capabilities for selecting and saving images and videos, documents, and audio clips. The application can select the Picker as required. The APIs of this module must be called in a UIAbility. Otherwise, the photoPicker or FilePicker application cannot be started.

Modules to Import

import  { picker } from '@kit.CoreFileKit';

DocumentViewPicker

Provides APIs for selecting and saving documents in different formats. Before using the APIs of DocumentViewPicker, you need to create a DocumentViewPicker instance.

System capability: SystemCapability.FileManagement.UserFileService

constructor12+

constructor(context: Context)

A constructor used to create a DocumentViewPicker instance. This constructor is recommended. For details about how to obtain the context, see getContext.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
context Context Yes Application context (only UIAbilityContext is supported). For details about the application context of the stage model, see Context.

Example

import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(()=>{
            let context = getContext (this) as common.Context; // Ensure that getContext (this) returns UIAbilityContext.
            let documentPicker = new picker.DocumentViewPicker(context);
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

constructor12+

constructor()

A constructor used to create a DocumentViewPicker instance. This constructor is not recommended due to the potential risk of operation failure.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Example

let documentPicker = new picker.DocumentViewPicker(); // Construction without parameter is not recommended. There is a possibility that the DocumentViewPicker instance fails to start.

constructor13+

constructor(context: Context, window: window.Window)

A constructor used to create a DocumentViewPicker object in a window created by an application. In other scenarios, you are advised to use constructor(context: Context) to create a DocumentViewPicker object.

Parameters

Name Type Mandatory Description
context Context Yes Application context (only UIAbilityContext is supported). For details about the application context of the stage model, see Context.
window window.Window Yes Window instance created by the application.

NOTE

Currently, only mobile phones are supported.

System capability: SystemCapability.FileManagement.UserFileService

Example

import { common } from '@kit.AbilityKit';
import { picker } from '@kit.CoreFileKit';
import { window } from '@kit.ArkUI';
@Entry
@Component
struct Index {
  @State message: string = 'hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(()=>{
            let context = getContext (this) as common.Context; // Ensure that getContext (this) returns UIAbilityContext.
            let windowClass: window.Window | undefined = undefined;
            windowClass = window.findWindow ('test'); // Ensure that the window has been created. Here, 'test' is the value of the name parameter when the window is created.
            let documentPicker = new picker.DocumentViewPicker(context, windowClass);
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

select

select(option?: DocumentSelectOptions): Promise<Array<string>>

Starts a documentPicker page for the user to select one or more documents. This API uses a promise to return the result. You can pass in DocumentSelectOptions.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option DocumentSelectOptions No Options for selecting documents. If this parameter is not specified, the documentPicker page is displayed by default.

Return value

Type Description
Promise<Array<string>> Promise used to return the URIs of the documents selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example07(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let documentSelectOptions = new picker.DocumentSelectOptions();
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.select(documentSelectOptions).then((documentSelectResult: Array<string>) => {
      console.info('DocumentViewPicker.select successfully, documentSelectResult uri: ' + JSON.stringify(documentSelectResult));
    }).catch((err: BusinessError) => {
      console.error('DocumentViewPicker.select failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

select

select(option: DocumentSelectOptions, callback: AsyncCallback<Array<string>>): void

Starts a documentPicker page for the user to select one or more documents. This API uses an asynchronous callback to return the result. You can pass in DocumentSelectOptions.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option DocumentSelectOptions Yes Options for selecting documents.
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the documents selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example08(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let documentSelectOptions = new picker.DocumentSelectOptions();
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.select(documentSelectOptions, (err: BusinessError, documentSelectResult: Array<string>) => {
      if (err) {
        console.error('DocumentViewPicker.select failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('DocumentViewPicker.select successfully, documentSelectResult uri: ' + JSON.stringify(documentSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

select

select(callback: AsyncCallback<Array<string>>): void

Starts a documentPicker page for the user to select one or more documents. This API uses an asynchronous callback to return the result.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

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

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example09(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.select((err: BusinessError, documentSelectResult: Array<string>) => {
      if (err) {
        console.error('DocumentViewPicker.select failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('DocumentViewPicker.select successfully, documentSelectResult uri: ' + JSON.stringify(documentSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(option?: DocumentSaveOptions): Promise<Array<string>>

Starts a documentPicker page for the user to save one or more documents. This API uses a promise to return the result. You can pass in DocumentSaveOptions to specify the file names to save.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option DocumentSaveOptions No Options for saving the documents. If this parameter is not specified, a documentPicker page will be displayed for the user to enter the names of the documents to save.

Return value

Type Description
Promise<Array<string>> Promise used to return the URIs of the documents saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example10(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let documentSaveOptions = new picker.DocumentSaveOptions();
    documentSaveOptions.newFileNames = ['DocumentViewPicker01.txt'];
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.save(documentSaveOptions).then((documentSaveResult: Array<string>) => {
      console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult));
    }).catch((err: BusinessError) => {
      console.error('DocumentViewPicker.save failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(option: DocumentSaveOptions, callback: AsyncCallback<Array<string>>): void

Starts a documentPicker page for the user to save one or more documents. This API uses an asynchronous callback to return the result. You can pass in DocumentSaveOptions to specify the file names to save.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option DocumentSaveOptions Yes Options for saving the documents.
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the documents saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example11(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let documentSaveOptions = new picker.DocumentSaveOptions();
    documentSaveOptions.newFileNames = ['DocumentViewPicker02.txt'];
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.save(documentSaveOptions, (err: BusinessError, documentSaveResult: Array<string>) => {
      if (err) {
        console.error('DocumentViewPicker.save failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(callback: AsyncCallback<Array<string>>): void

Starts a documentPicker page for the user to save one or more documents. This API uses an asynchronous callback to return the result.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

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

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example12(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.save((err: BusinessError, documentSaveResult: Array<string>) => {
      if (err) {
        console.error('DocumentViewPicker.save failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

getSelectedIndex14+;

getSelectedIndex(): number

Obtains the subscript of the file name extension type of the file saved.

This API is available only for 2-in-1 devices.

This method takes effect only when used with save().

getSelectedIndex() can be used only after DocumentSaveOptions.fileSuffixChoices is configured.

The subscript (number) returned by this method indicates the location of the filename extension specified in DocumentSaveOptions.fileSuffixChoices. If no filename extension is specified, getSelectedIndex() returns -1.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.FileManagement.UserFileService.FolderSelection

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function exampleIndex(context: common.Context) { // Ensure that context is converted from UIAbilityContext.
  try {
    let documentSaveOptions = new picker.DocumentSaveOptions();
    // Name of the file to save.
    documentSaveOptions.newFileNames = ['DocumentViewPicker01'];
    // File name extensions of the file to save.
    documentSaveOptions.fileSuffixChoices = ['txt', 'mp4', 'pdf'];
    let documentPicker = new picker.DocumentViewPicker(context);
    documentPicker.save(documentSaveOptions).then((documentSaveResult: Array<string>) => {
      if (documentSaveOptions.fileSuffixChoices != undefined && documentSaveResult != undefined) {
        // Obtain the subscript of the filename extension of the file saved.
        let index = documentPicker.getSelectedIndex();
        // Obtain the filename extension of the file saved.
        let selectedsuffix = documentSaveOptions.fileSuffixChoices[index];
        console.info ('DocumentViewPicker.save selectedsuffix is ' + selectedsuffix);
      }
      console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult));
    }).catch((err: BusinessError) => {
      console.error('DocumentViewPicker.save failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('DocumentViewPicker failed with err: ' + JSON.stringify(err));
  }
}

AudioViewPicker

Provides APIs for selecting and saving audio clips. Before using the APIs of AudioViewPicker, you need to create an AudioViewPicker instance.

System capability: SystemCapability.FileManagement.UserFileService

constructor12+

constructor(context: Context)

A constructor used to create an AudioViewPicker instance. This constructor is recommended. For details about how to obtain the context, see getContext.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
context Context Yes Application context (only UIAbilityContext is supported). For details about the application context of the stage model, see Context.

Example

import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(()=>{
            let context = getContext (this) as common.Context; // Ensure that getContext (this) returns UIAbilityContext.
            let audioPicker = new picker.AudioViewPicker(context);
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

constructor12+

constructor()

A constructor used to create an AudioViewPicker instance. This constructor is not recommended due to the potential risk of operation failure.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Example

let audioPicker = new picker.AudioViewPicker(); // Construction without parameter is not recommended. There is a possibility that the AudioViewPicker instance fails to start.

select

select(option?: AudioSelectOptions): Promise<Array<string>>

Starts an audioPicker page for the user to select one or more audio clips. This API uses a promise to return the result. You can pass in AudioSelectOptions.

NOTE
For details about how to use the URIs returned by this API, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option AudioSelectOptions No Options for selecting audio clips. If this parameter is not specified, the audioPicker page is displayed by default.

Return value

Type Description
Promise<Array<string>> Promise used to return the URIs of the audio clips selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example13(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let audioSelectOptions = new picker.AudioSelectOptions();
    let audioPicker = new picker.AudioViewPicker(context);
    audioPicker.select(audioSelectOptions).then((audioSelectResult: Array<string>) => {
      console.info('AudioViewPicker.select successfully, audioSelectResult uri: ' + JSON.stringify(audioSelectResult));
    }).catch((err: BusinessError) => {
      console.error('AudioViewPicker.select failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('AudioViewPicker failed with err: ' + JSON.stringify(err));
  }
}

select

select(option: AudioSelectOptions, callback: AsyncCallback<Array<string>>): void

Starts an audioPicker page for the user to select one or more audio clips. This API uses an asynchronous callback to return the result. You can pass in AudioSelectOptions.

NOTE
For details about how to use the URIs returned by this API, see Using a Document URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option AudioSelectOptions Yes Options for selecting audio clips.
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the audio clips selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example14(context: common.Context) { // Ensure that context is converted from UIAbilityContext.
  try {
    let audioSelectOptions = new picker.AudioSelectOptions();
    let audioPicker = new picker.AudioViewPicker(context);
    audioPicker.select(audioSelectOptions, (err: BusinessError, audioSelectResult: Array<string>) => {
      if (err) {
        console.error('AudioViewPicker.select failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('AudioViewPicker.select successfully, audioSelectResult uri: ' + JSON.stringify(audioSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('AudioViewPicker failed with err: ' + JSON.stringify(err));
  }
}

select

select(callback: AsyncCallback<Array<string>>): void

Starts an audioPicker page for the user to select one or more audio clips. This API uses an asynchronous callback to return the result.

NOTE
For details about how to use the URIs returned by this API, see Using a Document URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the audio clips selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example15(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let audioPicker = new picker.AudioViewPicker(context);
    audioPicker.select((err: BusinessError, audioSelectResult: Array<string>) => {
      if (err) {
        console.error('AudioViewPicker.select failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('AudioViewPicker.select successfully, audioSelectResult uri: ' + JSON.stringify(audioSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('AudioViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(option?: AudioSaveOptions): Promise<Array<string>>

Starts an audioPicker page (currently, a documentPicker page is displayed) for the user to save one or more audio clips. 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.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option AudioSaveOptions No Options for saving audio clips. If this parameter is not specified, an audioPicker page will be displayed for the user to enter the names of the files to save.

Return value

Type Description
Promise<Array<string>> Promise used to return the URIs of the audio clips saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example16(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let audioSaveOptions = new picker.AudioSaveOptions();
    audioSaveOptions.newFileNames = ['AudioViewPicker01.mp3'];
    let audioPicker = new picker.AudioViewPicker(context);
    audioPicker.save(audioSaveOptions).then((audioSaveResult: Array<string>) => {
      console.info('AudioViewPicker.save successfully, audioSaveResult uri: ' + JSON.stringify(audioSaveResult))
    }).catch((err: BusinessError) => {
      console.error('AudioViewPicker.save failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('AudioViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(option: AudioSaveOptions, callback: AsyncCallback<Array<string>>): void

Starts an audioPicker page (currently, a documentPicker page is displayed) for the user to save one or more audio clips. 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.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option AudioSaveOptions Yes Options for saving audio clips.
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the audio clips saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example17(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let audioSaveOptions = new picker.AudioSaveOptions();
    audioSaveOptions.newFileNames = ['AudioViewPicker02.mp3'];
    let audioPicker = new picker.AudioViewPicker(context);
    audioPicker.save(audioSaveOptions, (err: BusinessError, audioSaveResult: Array<string>) => {
      if (err) {
        console.error('AudioViewPicker.save failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('AudioViewPicker.save successfully, audioSaveResult uri: ' + JSON.stringify(audioSaveResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('AudioViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(callback: AsyncCallback<Array<string>>): void

Starts an audioPicker page (currently, a documentPicker page is displayed) for the user to save one or more audio clips. This API uses an asynchronous callback to return the result.

NOTE
For details about how to use the returned URIs, see Using a Document URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the audio clips saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example18(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let audioPicker = new picker.AudioViewPicker(context);
    audioPicker.save((err: BusinessError, audioSaveResult: Array<string>) => {
      if (err) {
        console.error('AudioViewPicker.save failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('AudioViewPicker.save successfully, audioSaveResult uri: ' + JSON.stringify(audioSaveResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('AudioViewPicker failed with err: ' + JSON.stringify(err));
  }
}

DocumentSelectMode11+

Enumerates the types of files that can be selected by Picker.

Only 2-in-1 devices are supported.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService.FolderSelection

Name Value Description
FILE 0 File type.
FOLDER 1 Folder.
MIXED 2 Mixed type of files and folders.

DocumentSelectOptions

Defines the options for selecting documents.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
maxSelectNumber10+ number No Maximum number of documents that can be selected.
Value range: 1 to 500.
Only the devices that have the required system capability can select folders, and only one folder can be selected at a time.
Default value: 1.
System capability: SystemCapability.FileManagement.UserFileService
defaultFilePathUri10+ string No Path of the documents or folder to select.
fileSuffixFilters10+ Array<string> No File name extensions of the documents to select. The value is a string array. Each element specifies an option, which includes at most two parts with a vertical bar (
selectMode11+ DocumentSelectMode No Only 2in1 devices are supported. The default value is File.
System capability: SystemCapability.FileManagement.UserFileService.FolderSelection
authMode12+ boolean No Whether to start Picker.
Default value: false. If authMode is true, defaultFilePathUri is mandatory, which specifies the URI of the file allowed to access. Only 2in1 devices are supported.
System capability: SystemCapability.FileManagement.UserFileService.FolderSelection
multiAuthMode15+ boolean No The batch authorization mode is supported. The default value false indicates the non-batch authorization mode. When multAuthMode is set to true, the batch authorization mode is used. And only the multiUriArray parameter takes effect. Only mobile phones are supported.
Atomic service API: This API can be used in atomic services since API version 15.
multiUriArray15+ Array<string> No URI array for batch authorization. (Only files are supported. Folders are not supported.) This parameter is used together with multAuthMode. This parameter does not take effect when multAuthMode is set to false. Only mobile phones are supported.
Atomic service API: This API can be used in atomic services since API version 15.
mergeMode15+ MergeTypeMode No Enables the aggregation view mode. The aggregation view of the file management application can be started. The default value is DEFAULT, indicating that this parameter does not take effect and the view is not an aggregation view. If this parameter is set to a value other than DEFAULT, other parameters do not take effect. Only mobile phones are supported.
Atomic service API: This API can be used in atomic services since API version 15.

DocumentPickerMode12+

Enumerates the modes for saving documents.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Name Value Description
DEFAULT 0 Standard mode.
DOWNLOAD 1 Download mode.

MergeTypeMode15+

Enumerates file aggregation types. Only mobile phones are supported.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.FileManagement.UserFileService

Name Value Description
DEFAULT 0 Default mode, indicating that this parameter does not take effect.
AUDIO 1 Audio mode.
VIDEO 2 Video mode.
DOCUMENT 3 Document mode.
PICTURE 4 Image mode.

DocumentSaveOptions

Defines the options for saving documents.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
newFileNames Array<string> No File names of the documents to save. If this parameter is not specified, the user needs to enter the document names.
defaultFilePathUri10+ string No Path of the documents or folder to save.
fileSuffixChoices10+ Array<string> No File name extensions of the documents to save. The value is a string array. Each element specifies an option, which includes at most two parts with a vertical bar (
pickerMode12+ DocumentPickerMode No Mode for starting Picker.
Default value: DEFAULT. If pickerMode is DOWNLOAD, the settings of newFileNames, defaultFilePathUri, and fileSuffixChoices do not take effect.

AudioSelectOptions

Defines the options for selecting audio clips.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
maxSelectNumber12+ number No Maximum number of audio clips that can be selected.
Default value: 1
Value range: 1 to 500

AudioSaveOptions

Defines the options for saving audio clips.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
newFileNames Array<string> No File names of the audio clips to save. If this parameter is not specified, the user needs to enter the document names.

PhotoViewPicker(deprecated)

Provides APIs for selecting and saving images/videos. You are advised to use PhotoViewPicker of PhotoAccessHelper to select files. Before using the APIs of PhotoViewPicker, you need to create a PhotoViewPicker instance.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoViewPicker instead.

System capability: SystemCapability.FileManagement.UserFileService

constructor12+

constructor(context: Context)

System capability: SystemCapability.FileManagement.UserFileService

A constructor used to create a PhotoViewPicker instance. This constructor is recommended. For details about how to obtain the context, see getContext.

Example

import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(()=>{
            let context = getContext (this) as common.Context; // Ensure that getContext (this) returns UIAbilityContext.
            let photoPicker = new picker.PhotoViewPicker(context);
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

constructor12+

constructor()

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.FileManagement.UserFileService

A constructor used to create a PhotoViewPicker instance. This constructor is not recommended due to the potential risk of operation failure.

Example

let photoPicker = new picker.PhotoViewPicker(); // Construction without parameter is not recommended. There is a possibility that the PhotoViewPicker instance fails to start.

select

select(option?: PhotoSelectOptions): Promise<PhotoSelectResult>

Starts a photoPicker page for the user to select one or more images/videos. This API uses a promise to return the result. You can pass in PhotoSelectOptions to specify the type and maximum number of the files to select.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoViewPicker#select instead.

NOTE
The photoUris in the PhotoSelectResult object returned by this API can be used only by photoAccessHelper.getAssets. For details, see Using a Media File URI.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option PhotoSelectOptions No Options for selecting images/videos. If this parameter is not specified, images and videos are selected by default. A maximum of 50 files can be selected.

Return value

Type Description
Promise<PhotoSelectResult> Promise used to return a PhotoSelectResult object.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example01(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let photoSelectOptions = new picker.PhotoSelectOptions();
    photoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE;
    photoSelectOptions.maxSelectNumber = 5;
    let photoPicker = new picker.PhotoViewPicker(context);
    photoPicker.select(photoSelectOptions).then((photoSelectResult: picker.PhotoSelectResult) => {
      console.info('PhotoViewPicker.select successfully, photoSelectResult uri: ' + JSON.stringify(photoSelectResult));
    }).catch((err: BusinessError) => {
      console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

select

select(option: PhotoSelectOptions, callback: AsyncCallback<PhotoSelectResult>): void

Starts a photoPicker page for the user to select one or more images/videos. This API uses an asynchronous callback to return the result. You can pass in PhotoSelectOptions to specify the type and maximum number of the files to select.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoViewPicker#select instead.

NOTE
The photoUris in the PhotoSelectResult object returned by this API can be used only by photoAccessHelper.getAssets. For details, see Using a Media File URI.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option PhotoSelectOptions Yes Options for selecting images/videos.
callback AsyncCallback<PhotoSelectResult> Yes Callback used to return information about the images or videos selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example02(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let photoSelectOptions = new picker.PhotoSelectOptions();
    photoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE;
    photoSelectOptions.maxSelectNumber = 5;
    let photoPicker = new picker.PhotoViewPicker(context);
    photoPicker.select(photoSelectOptions, (err: BusinessError, photoSelectResult: picker.PhotoSelectResult) => {
      if (err) {
        console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('PhotoViewPicker.select successfully, photoSelectResult uri: ' + JSON.stringify(photoSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

select

select(callback: AsyncCallback<PhotoSelectResult>): void

Starts a photoPicker page for the user to select one or more images/videos. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoViewPicker#select instead.

NOTE
The photoUris in the PhotoSelectResult object returned by this API can be used only by photoAccessHelper.getAssets. For details, see Using a Media File URI.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
callback AsyncCallback<PhotoSelectResult> Yes Callback used to return information about the images or videos selected.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example03(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let photoPicker = new picker.PhotoViewPicker(context);
    photoPicker.select((err: BusinessError, photoSelectResult: picker.PhotoSelectResult) => {
      if (err) {
        console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('PhotoViewPicker.select successfully, photoSelectResult uri: ' + JSON.stringify(photoSelectResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(option?: PhotoSaveOptions): Promise<Array<string>>

Starts a photoPicker page for the user to save one or more images/videos. This API uses a promise to return the result. You can pass in PhotoSaveOptions to specify the file names of the images/videos to save.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use SaveButton instead.

NOTE
This API saves files in Files, not in Gallery. For details about how to use the returned URIs, see Using a Document URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option PhotoSaveOptions No Options for saving images/videos. If this parameter is not specified, a photoPicker page will be displayed for the user to enter the names of the files to save.

Return value

Type Description
Promise<Array<string>> Promise used to return the URIs of the files saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example04(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let photoSaveOptions = new picker.PhotoSaveOptions();
    photoSaveOptions.newFileNames = ['PhotoViewPicker01.jpg', 'PhotoViewPicker01.mp4'];
    let photoPicker = new picker.PhotoViewPicker(context);
    photoPicker.save(photoSaveOptions).then((photoSaveResult: Array<string>) => {
      console.info('PhotoViewPicker.save successfully, photoSaveResult uri: ' + JSON.stringify(photoSaveResult));
    }).catch((err: BusinessError) => {
      console.error('PhotoViewPicker.save failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
      console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(option: PhotoSaveOptions, callback: AsyncCallback<Array<string>>): void

Starts a photoPicker page for the user to save one or more images/videos. This API uses an asynchronous callback to return the result. You can pass in PhotoSaveOptions to specify the file names of the images/videos to save.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use SaveButton instead.

NOTE
This API saves files in Files, not in Gallery. For details about how to use the returned URIs, see Using a Document URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Name Type Mandatory Description
option PhotoSaveOptions Yes Options for saving images/videos.
callback AsyncCallback<Array<string>> Yes Callback invoked to return the URIs of the files saved.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example05(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let photoSaveOptions = new picker.PhotoSaveOptions();
    photoSaveOptions.newFileNames = ['PhotoViewPicker02.jpg','PhotoViewPicker02.mp4'];
    let photoPicker = new picker.PhotoViewPicker(context);
    photoPicker.save(photoSaveOptions, (err: BusinessError, photoSaveResult: Array<string>) => {
      if (err) {
        console.error('PhotoViewPicker.save failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('PhotoViewPicker.save successfully, photoSaveResult uri: ' + JSON.stringify(photoSaveResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

save

save(callback: AsyncCallback<Array<string>>): void

Starts a photoPicker page for the user to save one or more images/videos. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use SaveButton instead.

NOTE
This API saves files in Files, not in Gallery. For details about how to use the returned URIs, see Using a Document URI.

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

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import  { picker } from '@kit.CoreFileKit';
async function example06(context: common.Context) {// Ensure that context is converted from UIAbilityContext.
  try {
    let photoPicker = new picker.PhotoViewPicker(context);
    photoPicker.save((err: BusinessError, photoSaveResult: Array<string>) => {
      if (err) {
        console.error('PhotoViewPicker.save failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('PhotoViewPicker.save successfully, photoSaveResult uri: ' + JSON.stringify(photoSaveResult));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

PhotoViewMIMETypes(deprecated)

Enumerates the media file types that can be selected.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoViewMIMETypes instead.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.FileManagement.UserFileService

Name Value Description
IMAGE_TYPE 'image/*' Image.
VIDEO_TYPE 'video/*' Video.
IMAGE_VIDEO_TYPE '*/*' Image and video.

PhotoSelectOptions(deprecated)

Defines the options for selecting images/videos.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoSelectOptions instead.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
MIMEType PhotoViewMIMETypes No Media file types to select. IMAGE_VIDEO_TYPE is used by default.
maxSelectNumber number No Maximum number of media files that can be selected. The default value is 50, and the maximum value is 500.

PhotoSelectResult(deprecated)

Defines information about the images/videos selected.

NOTE

This API is supported since API version 9 and deprecated since API version 12. Use photoAccessHelper.PhotoSelectResult instead.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
photoUris Array<string> Yes URIs of the media files selected. This URI array can be used only by photoAccessHelper.getAssets. For details, see Using a Media File URI.
isOriginalPhoto boolean Yes Whether the selected image is the original one. The value true means the selected image is the original one, and false means the opposite.

PhotoSaveOptions(deprecated)

Defines the options for saving images or videos.

NOTE

This API is supported since API version 9 and deprecated since API version 12. There is no substitute API.

System capability: SystemCapability.FileManagement.UserFileService

Name Type Mandatory Description
newFileNames Array<string> No Files names of the images or videos to save. If this parameter is not specified, the user needs to enter the file names.
Loading...
马建仓 AI 助手
尝试更多
代码解读
代码找茬
代码优化
其他
1
https://gitee.com/openharmony/docs.git
git@gitee.com:openharmony/docs.git
openharmony
docs
docs
OpenHarmony-5.0.3-Release

搜索帮助