@ohos.file.picker (Picker)

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

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.

Modules to Import

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. You are advised to use PhotoViewPicker of PhotoAccessHelper to select images and videos.

System capability: SystemCapability.FileManagement.UserFileService

Example

let photoPicker = new picker.PhotoViewPicker();

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
The photoUris in the PhotoSelectResult object returned by this API can be used only by calling photoAccessHelper.getAssets() with temporary authorization. For details, see Using a Media File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
async function example01() {
  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: 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
The photoUris in the PhotoSelectResult object returned by this API can be used only by calling photoAccessHelper.getAssets() with temporary authorization. For details, see Using a Media File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example02() {
  try {
    let PhotoSelectOptions = new picker.PhotoSelectOptions();
    PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE;
    PhotoSelectOptions.maxSelectNumber = 5;
    let photoPicker = new picker.PhotoViewPicker();
    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
The photoUris in the PhotoSelectResult object returned by this API can be used only by calling photoAccessHelper.getAssets() with temporary authorization. For details, see Using a Media File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example03() {
  try {
    let photoPicker = new picker.PhotoViewPicker();
    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 saves files in Files, not in Gallery. For details about how to use the returned URIs, see Using a File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
async function example04() {
  try {
    let PhotoSaveOptions = new picker.PhotoSaveOptions();
    PhotoSaveOptions.newFileNames = ['PhotoViewPicker01.jpg', 'PhotoViewPicker01.mp4'];
    let photoPicker = new picker.PhotoViewPicker();
    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 saves files in Files, not in Gallery. For details about how to use the returned URIs, see Using a File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example05() {
  try {
    let PhotoSaveOptions = new picker.PhotoSaveOptions();
    PhotoSaveOptions.newFileNames = ['PhotoViewPicker02.jpg','PhotoViewPicker02.mp4'];
    let photoPicker = new picker.PhotoViewPicker();
    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 saves files in Files, not in Gallery. For details about how to use the returned URIs, see Using a File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example06() {
  try {
    let photoPicker = new picker.PhotoViewPicker();
    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));
  }
}

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

Example

let documentPicker = new picker.DocumentViewPicker();

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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
async function example07() {
  try {
    let DocumentSelectOptions = new picker.DocumentSelectOptions();
    let documentPicker = new picker.DocumentViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example08() {
  try {
    let DocumentSelectOptions = new picker.DocumentSelectOptions();
    let documentPicker = new picker.DocumentViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example09() {
  try {
    let documentPicker = new picker.DocumentViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
async function example10() {
  try {
    let DocumentSaveOptions = new picker.DocumentSaveOptions();
    DocumentSaveOptions.newFileNames = ['DocumentViewPicker01.txt'];
    let documentPicker = new picker.DocumentViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example11() {
  try {
    let DocumentSaveOptions = new picker.DocumentSaveOptions();
    DocumentSaveOptions.newFileNames = ['DocumentViewPicker02.txt'];
    let documentPicker = new picker.DocumentViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example12() {
  try {
    let documentPicker = new picker.DocumentViewPicker();
    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));
  }
}

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

Example

let audioPicker = new picker.AudioViewPicker();

select

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

Starts an audioPicker page (currently, a documentPicker page is displayed) 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 returned URIs, see Using a File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
async function example13() {
  try {
    let AudioSelectOptions = new picker.AudioSelectOptions();
    let audioPicker = new picker.AudioViewPicker();
    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 (currently, a documentPicker page is displayed) 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 returned URIs, see Using a File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example14() {
  try {
    let AudioSelectOptions = new picker.AudioSelectOptions();
    let audioPicker = new picker.AudioViewPicker();
    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 (currently, a documentPicker page is displayed) 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 returned URIs, see Using a File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example15() {
  try {
    let audioPicker = new picker.AudioViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
async function example16() {
  try {
    let AudioSaveOptions = new picker.AudioSaveOptions();
    AudioSaveOptions.newFileNames = ['AudioViewPicker01.mp3'];
    let audioPicker = new picker.AudioViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example17() {
  try {
    let AudioSaveOptions = new picker.AudioSaveOptions();
    AudioSaveOptions.newFileNames = ['AudioViewPicker02.mp3'];
    let audioPicker = new picker.AudioViewPicker();
    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 File URI.

System capability: SystemCapability.FileManagement.UserFileService

Parameters

Example

import { BusinessError } from '@ohos.base';
async function example18() {
  try {
    let audioPicker = new picker.AudioViewPicker();
    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));
  }
}

PhotoViewMIMETypes

Enumerates the media file types that can be selected.

System capability: SystemCapability.FileManagement.UserFileService

PhotoSelectOptions

Defines the options for selecting images/videos.

System capability: SystemCapability.FileManagement.UserFileService

PhotoSelectResult

Defines information about the images/videos selected.

System capability: SystemCapability.FileManagement.UserFileService

PhotoSaveOptions

Defines the options for saving images/videos.

System capability: SystemCapability.FileManagement.UserFileService

DocumentSelectOptions

Defines the options for selecting documents.

System capability: SystemCapability.FileManagement.UserFileService

DocumentSaveOptions

Defines the options for saving documents.

System capability: SystemCapability.FileManagement.UserFileService

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 clips.

System capability: SystemCapability.FileManagement.UserFileService