Skip to content

API

Jump to bottom
Miguel Ruivo edited this page Jul 20, 2020 · 49 revisions

Filters

All the paths can be filtered using one of the following enumerations:

Filter Description
FileType.any Will let you pick all available files.
FileType.custom Will let you pick a path for the extension matching the allowedExtensions provided.
FileType.image Will let you pick an image file. Opens gallery (Photos app) on iOS.
FileType.video Will let you pick a video file. Opens gallery (Photos app) on iOS.
FileType.media Will let you pick either video or images. Opens gallery (Photos app) on iOS.
FileType.audio Will let you pick an audio file. Opens music on iOS. Note that DRM protected files won't provide a path, null will be returned instead.

Parameters

There are a few common parameters that all picking methods support, those are listed below:

Parameter Type Description Default
type FileType Defines the type of the filtered files. FileType.any
allowedExtensions List<String> Accepts a list of allowed extensions to be filtered. Eg. [.pdf, .jpg] -
allowCompression bool Defines whether image and/or video files should be compressed automatically by OS when picked. On Android has no effect as it always returns the original or integral file copy. true
onFileLoading Function(FilePickerStatus) When provided, will receive the processing status of picked files. This is particularly useful if you want to display a loading dialog or so when files are being downloaded/cached -

Methods

◉ FilePicker.getFilePath()

Will let you pick a single file. This receives two optional parameters: the fileType for specifying the type of the picker and a fileExtension parameter to filter selectable files.

NOTE: You must use FileType.custom when providing allowedExtensions, else it will throw an exception.

Usage example

String filePath;

// Will let you pick one file path, from all extensions
filePath = await FilePicker.getFilePath(type: FileType.any);

// Will filter and only let you pick files with svg and pdf extension
filePath = await FilePicker.getFilePath(type: FileType.custom, allowedExtensions: ['svg', 'pdf']);

◉ FilePicker.getMultiFilePath()

Will let you select multiple files and retrieve its path at once. Optionally you can provide a fileExtension parameter to filter the allowed selectable files. Will return a Map<String,String> with the files name (key) and corresponding path (value) of all selected files.

NOTE: Picking multiple paths from iOS gallery uses DKImagePickerController, thus, any issue directly related to the picker when picking multiple files from gallery, should be open there.

Usage example

Map<String,String> filesPaths;

// Will let you pick multiple files of any format at once
filePaths = await FilePicker.getMultiFilePath();

// Will let you pick multiple pdf files at once
filePaths = await FilePicker.getMultiFilePath(allowedExtensions: ['pdf']);

// Will let you pick multiple image files at once
filePaths = await FilePicker.getMultiFilePath(type: FileType.image); 

List<String> allNames = filePaths.keys; // List of all file names
List<String> allPaths = filePaths.values; // List of all paths
String someFilePath = filePaths['fileName']; // Access a file path directly by its name (matching a key)

◉ FilePicker.getFile()

A helper method that wraps your single file path pick into a File.

Usage example

// Will return a File object directly from the selected file
File file = await FilePicker.getFile(type: FileType.any);

◉ FilePicker.getMultiFile()

Similar to the last, it's a helper method that wraps all the picked files, into a List<File> so they are ready to use. Have in mind, that using getMultiPath will give you a Map<String,String> containing a k,v pair of the file name and path respectively while with this, you'll have only the File.

Usage example

// Will return a List<File> object directly from the selected files
List<File> files = await FilePicker.getMultiFile(type: FileType.any);

◉ FilePicker.getDirectoryPath()

Will let you select and pick a directory path.

Platform Result
iOS Requires iOS 11 or above
Android Requires SDK 21 or above
Desktop -
Web Not supported

◉ FilePicker.clearTemporaryFiles()

An utility method that will explicitly prune cached files from the picker. This is not required as the system will take care on its own, however, sometimes you may want to remove them, specially if your app handles a lot of files.

Platform Result
iOS All picked files are cached, so this will immediately remove them.
Android Typically files picked from remote providers or local files which the path can't be handled otherwise.
Desktop & Web Not implemented as it won't have any effect. Paths are always referencing the original files.
Clone this wiki locally