Non-standard: This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
The LocalFileSystem
interface of the File System API gives you access to a sandboxed file system. The methods are implemented by window and worker objects.
This section includes a few key concepts for the methods.
You request access to a sandboxed file system by calling window.requestFileSystem()
. The argument of a successful callback is the FileSystem
object, which has two properties: the name and root of the file system.
You can call the method more than once if you want to create two file systems: one that's temporary and one that's persistent. (To learn more about the storage types, see the Basic Concepts article.) In most cases, you need to create only one file system, but in a few cases, it might be useful to create a second one. For example, if you were to create a mail app, you might create a temporary storage for caching assets (like images and attachments) to speed up performance, while creating persistent storage for unique data—such as drafts of emails that were composed while offline—that should not be lost before they are backed up into the cloud.
The requestFileSystem()
method lets you ask for PERSISTENT
or TEMPORARY
storage. Persistent storage is storage that stays in the browser unless the app or the user removes it, but the user must grant you permission before you can use it. In contrast, temporary storage is automatically granted without any user permission, but it can be expunged by the browser at any time.
To use PERSISTENT
storage with the File System API, Chrome exposes a requestQuota API. So to request storage, you need to do something like the following:
var requestedBytes = 1024*1024*10;
navigator.webkitPersistentStorage.requestQuota (
requestedBytes, function(grantedBytes) {
window.requestFileSystem(PERSISTENT, grantedBytes, onInitFs, errorHandler);
}, function(e) { console.log('Error', e); }
);
Your user must grant your app permission to store data locally before your app can use persistent storage. Once your user grants it, you don't need to call requestQuota()
again. Subsequent calls are a noop.
Another API, the Quota Management API, lets you query an origin's current quota usage and allocation using window.webkitPersistentStorage.queryUsageAndQuota()
. To learn more, see this StackOverflow Answer. (An older version of the API is described at Managing HTML5 Offline Storage.)
The file system is sandboxed to a single origin. This means that your app cannot read, or write the files of another app's files. Your app cannot access files in an arbitrary folder (such as, My Pictures, My Documents) on the user's hard drive either. For more information about restrictions, see the Basic Concepts article.
The following is a code snippet that shows how you can request a file system storage.
window.requestFileSystem = window.requestFileSystem || window.webkitRequestFileSystem;
window.requestFileSystem(window.PERSISTENT, 1024*1024,onInitFs,errorHandler);
Requests a file system where data should be stored. You access a sandboxed file system by requesting a LocalFileSystem
object using this global method, window.requestFileSystem()
.
void requestFileSystem(
in unsigned short type,
in unsigned long long size,
in FileSystemCallback successCallback,
in ErrorCallback errorCallback
);
Parameters
-
type
-
The storage type of the file system. The values can be either TEMPORARY
or PERSISTENT
.
-
size
-
The storage space—in bytes—that you need for your app.
-
successCallback
-
The success callback that is called when the browser provides a file system. Its argument is the FileSystem
object with two properties:
- name - the unique name assigned by the browser to the file system.
- root - the read-only
DirectoryEntry
object representing the root of the file system.
-
opt_errorCallback
-
The error callback that is called when errors happen or when the request to obtain the file system is denied. Its argument is the FileError
object.
Returns
None.
Exceptions
This method can raise an FileError with the following code:
Lets you look up the entry for a file or directory with a local URL.
void resolveLocalFileSystemURL(
in DOMString url,
in EntryCallback successCallback,
in optional ErrorCallback errorCallback
);
Parameters
-
url
-
The URL of a local file in the file system.
-
successCallback
-
The success callback that is called when the browser provides the file or directory for the supplied URL.
-
errorCallback
-
The error callback that is called when errors happen or when the request to obtain the entry object is denied.
Returns
None.
Exceptions
This method can raise an FileError with the following code: