The 2017 Ionic Developer Survey Results are in!

File

Improve this doc

This plugin implements a File API allowing read/write access to files residing on the device.

The File class implements static convenience functions to access files and directories.

Example:

import { File } from '@ionic-native/file';

constructor(private file: File) { }

...

this.file.checkDir(this.file.dataDirectory, 'mydir').then(_ => console.log('Directory exists')).catch(err => console.log('Directory doesnt exist'));

This plugin is based on several specs, including : The HTML5 File API http: //www.w3.org/TR/FileAPI/ The (now-defunct) Directories and System extensions Latest: http: //www.w3.org/TR/2012/WD-file-system-api-20120417/ Although most of the plugin code was written when an earlier spec was current: http: //www.w3.org/TR/2011/WD-file-system-api-20110419/ It also implements the FileWriter spec : http: //dev.w3.org/2009/dap/file-system/file-writer.html

Repo: https://github.com/apache/cordova-plugin-file

Installation

  1. Install the Cordova and Ionic Native plugins:
    $ ionic cordova plugin add cordova-plugin-file
    $ npm install --save @ionic-native/file
    
  2. Add this plugin to your app's module

Supported platforms

Instance Members

applicationDirectory

Read-only directory where the application is installed.

applicationStorageDirectory

Read-only directory where the application is installed.

dataDirectory

Where to put app-specific data files.

cacheDirectory

Cached files that should survive app restarts. Apps should not rely on the OS to delete files in here.

externalApplicationStorageDirectory

Android: the application space on external storage.

externalDataDirectory

Android: Where to put app-specific data files on external storage.

externalCacheDirectory

Android: the application cache on external storage.

externalRootDirectory

Android: the external storage (SD card) root.

tempDirectory

iOS: Temp directory that the OS can clear at will.

syncedDataDirectory

iOS: Holds app-specific files that should be synced (e.g. to iCloud).

documentsDirectory

iOS: Files private to the app, but that are meaningful to other applications (e.g. Office files)

sharedDirectory

BlackBerry10: Files globally available to all apps

cordovaFileError

getFreeDiskSpace()

Get free disk space in Bytes

Returns: Promise<number> Returns a promise that resolves with the remaining free disk space in Bytes

checkDir(path, dir)

Check if a directory exists in a certain path, directory.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

dir string

Name of directory to check

Returns: Promise<boolean> Returns a Promise that resolves to true if the directory exists or rejects with an error.

createDir(path, dirName, replace)

Creates a new directory in the specific path. The replace boolean value determines whether to replace an existing directory with the same name. If an existing directory exists and the replace value is false, the promise will fail and return an error.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

dirName string

Name of directory to create

replace boolean

If true, replaces file with same name. If false returns error

Returns: Promise<DirectoryEntry> Returns a Promise that resolves with a DirectoryEntry or rejects with an error.

removeDir(path, dirName)

Remove a directory at a given path.

Param Type Details
path string

The path to the directory

dirName string

The directory name

Returns: Promise<RemoveResult> Returns a Promise that resolves to a RemoveResult or rejects with an error.

moveDir(path, dirName, newPath, newDirName)

Move a directory to a given path.

Param Type Details
path string

The source path to the directory

dirName string

The source directory name

newPath string

The destionation path to the directory

newDirName string

The destination directory name

Returns: Promise<DirectoryEntry|Entry> Returns a Promise that resolves to the new DirectoryEntry object or rejects with an error.

copyDir(path, dirName, newPath, newDirName)

Copy a directory in various methods. If destination directory exists, will fail to copy.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

dirName string

Name of directory to copy

newPath string

Base FileSystem of new location

newDirName string

New name of directory to copy to (leave blank to remain the same)

Returns: Promise<Entry> Returns a Promise that resolves to the new Entry object or rejects with an error.

listDir(path, dirName)

List files and directory from a given path.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

dirName string

Name of directory

Returns: Promise<Entry[]> Returns a Promise that resolves to an array of Entry objects or rejects with an error.

removeRecursively(path, dirName)

Removes all files and the directory from a desired location.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

dirName string

Name of directory

Returns: Promise<RemoveResult> Returns a Promise that resolves with a RemoveResult or rejects with an error.

checkFile(path, file)

Check if a file exists in a certain path, directory.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

file string

Name of file to check

Returns: Promise<boolean> Returns a Promise that resolves with a boolean or rejects with an error.

createFile(path, fileName, replace)

Creates a new file in the specific path. The replace boolean value determines whether to replace an existing file with the same name. If an existing file exists and the replace value is false, the promise will fail and return an error.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

fileName string

Name of file to create

replace boolean

If true, replaces file with same name. If false returns error

Returns: Promise<FileEntry> Returns a Promise that resolves to a FileEntry or rejects with an error.

removeFile(path, fileName)

Removes a file from a desired location.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

fileName string

Name of file to remove

Returns: Promise<RemoveResult> Returns a Promise that resolves to a RemoveResult or rejects with an error.

writeFile(path, fileName, text, options)

Write a new file to the desired location.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

fileName string

path relative to base path

text string|Blob

content or blob to write

options IWriteOptions

replace file if set to true. See WriteOptions for more information.

Returns: Promise<any> Returns a Promise that resolves to updated file entry or rejects with an error.

writeExistingFile(path, fileName, text)

Write to an existing file.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

fileName string

path relative to base path

text string|Blob

content or blob to write

Returns: Promise<void> Returns a Promise that resolves or rejects with an error.

readAsText(path, file)

Read the contents of a file as text.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

file string

Name of file, relative to path.

Returns: Promise<string> Returns a Promise that resolves with the contents of the file as string or rejects with an error.

readAsDataURL(path, file)

Read file and return data as a base64 encoded data url. A data url is of the form: data: [][;base64],

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

file string

Name of file, relative to path.

Returns: Promise<string> Returns a Promise that resolves with the contents of the file as data URL or rejects with an error.

readAsBinaryString(path, file)

Read file and return data as a binary data.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

file string

Name of file, relative to path.

Returns: Promise<string> Returns a Promise that resolves with the contents of the file as string rejects with an error.

readAsArrayBuffer(path, file)

Read file and return data as an ArrayBuffer.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

file string

Name of file, relative to path.

Returns: Promise<ArrayBuffer> Returns a Promise that resolves with the contents of the file as ArrayBuffer or rejects with an error.

moveFile(path, fileName, newPath, newFileName)

Move a file to a given path.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

fileName string

Name of file to move

newPath string

Base FileSystem of new location

newFileName string

New name of file to move to (leave blank to remain the same)

Returns: Promise<Entry> Returns a Promise that resolves to the new Entry or rejects with an error.

copyFile(path, fileName, newPath, newFileName)

Copy a file in various methods. If file exists, will fail to copy.

Param Type Details
path string

Base FileSystem. Please refer to the iOS and Android filesystems above

fileName string

Name of file to copy

newPath string

Base FileSystem of new location

newFileName string

New name of file to copy to (leave blank to remain the same)

Returns: Promise<Entry> Returns a Promise that resolves to an Entry or rejects with an error.

resolveLocalFilesystemUrl(fileUrl)

Resolves a local file system URL

Param Type Details
fileUrl string

file system url

Returns: Promise<Entry>

resolveDirectoryUrl(directoryUrl)

Resolves a local directory url

Param Type Details
directoryUrl string

directory system url

Returns: Promise<DirectoryEntry>

getDirectory(directoryEntry, directoryName, flags)

Get a directory

Param Type Details
directoryEntry DirectoryEntry

Directory entry, obtained by resolveDirectoryUrl method

directoryName string

Directory name

flags Flags

Options

Returns: Promise<DirectoryEntry>

getFile(directoryEntry, fileName, flags)

Get a file

Param Type Details
directoryEntry DirectoryEntry

Directory entry, obtained by resolveDirectoryUrl method

fileName string

File name

flags Flags

Options

Returns: Promise<FileEntry>

IFile

Entry

DirectoryEntry

DirectoryReader

FileSystem

API

Native

General