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.
import { picker } from '@kit.CoreFileKit';
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
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%')
}
}
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.
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(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(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(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(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(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(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));
}
}
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));
}
}
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
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%')
}
}
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(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(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(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(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(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(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));
}
}
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. |
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. |
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. |
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. |
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. |
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 |
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. |
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
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%')
}
}
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(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(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(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(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(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(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));
}
}
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. |
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. |
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. |
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. |
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。