The FileSystemEntry interface of the File and Directory Entries API represents a single in a file system. The entry can be a file or a directory (directories are represented by the {{domxref("DirectoryEntry")}} interface. It includes methods for working with files—including copying, moving, removing, and reading files—as well as information about a file it points to—including the file name and its path from the root to the entry.
Because this is a non-standard API, whose specification is not currently on a standards track, it's important to keep in mind that not all browsers implement it, and those that do may implement only small portions of it. Check the {{anch("Browser compatibility")}} section for details.
Basic concepts
You don't create FileSystemEntry objects directly. Instead, you will receive an object based on this interface through other APIs. This interface serves as a base class for the {{domxref("FileSystemFileEntry")}} and {{domxref("FileSystemDirectoryEntry")}} interfaces, which provide features specific to file system entries representing files and directories, respectively.
The FileSystemEntry interface includes methods that you would expect for manipulating files and directories, but it also includes a convenient method for obtaining the URL of the entry: toURL(). It also introduces a new URL scheme: filesystem:.
You can use the filesystem: scheme on Google Chrome to see all the files and folders that are stored in the origin of your app. Just use filesystem: scheme for the root directory of the origin of the app. For example, if your app is in https://www.html5rocks.com, open filesystem:https://www.html5rocks.com/temporary/ in a tab. Chrome shows a read-only list of all the files and folders stored the origin of your app.
Example
To see an example of how toURL() works, see the method description. The snippet below shows you how you can remove a file by name.
// Taking care of the browser-specific prefixes.
window.requestFileSystem = window.requestFileSystem || window.webkitRequestFileSystem;
...
// Opening a file system with temporary storage
window.requestFileSystem(TEMPORARY, 1024*1024 /*1MB*/, function(fs) {
fs.root.getFile('log.txt', {}, function(fileEntry) {
fileEntry.remove(function() {
console.log('File removed.');
}, onError);
}, onError);
}, onError);
Method overview
void getMetadata (in MetadataCallback successCallback, in optional ErrorCallback errorCallback); |
void moveTo (in DirectoryEntry parent, optional DOMString newName, in optional EntryCallback successCallback, in optional ErrorCallback errorCallback); |
void copyTo (in DirectoryEntry parent, in optional DOMString newName, in optional EntryCallback successCallback, in optional ErrorCallback errorCallback); |
void toURL (in optional DOMString mimeType); |
void remove (in VoidCallback successCallback, in optional ErrorCallback errorCallback); |
void getParent (in EntryCallback successCallback, in optional ErrorCallback errorCallback); |
Properties
This interface provides the following properties.
- filesystem {{ReadOnlyInline}}
- A {{domxref("FileSystem")}} object representing the file system in which the entry is located.
- fullPath {{ReadOnlyInline}}
- A {{domxref("DOMString")}} object which provides the full, absolute path from the file system's root to the entry; it can also be thought of as a path which is relative to the root directory, prepended with a "/" character.
- isDirectory {{ReadOnlyInline}}
- A {{jsxref("Boolean")}} which is
trueif the entry represents a directory; otherwise, it'sfalse. - isFile {{ReadOnlyInline}}
- A Boolean which is
trueif the entry represents a file. If it's not a file, this value isfalse. - name {{ReadOnlyInline}}
- A {{domxref("DOMString")}} containing the name of the entry (the final part of the path, after the last "/" character).
Methods
getMetadata()
Look up last modification date of the entry.
void getMetadata ( in MetadataCallback ErrorCallback );
Parameter
- successCallback
- A callback that is called with the time of the last modification.
- errorCallback
- A callback that is called when errors happen.
Returns
void
moveTo()
Move an entry to a different location on the file system. Moving a file over an existing file replaces that existing file. A move of a directory on top of an existing empty directory replaces that directory.
You can also use this method for renaming files. You can keep it in the same location and then define the newName parameter.
You cannot do the following:
- Move a directory inside itself or to any child at any depth
- Move an entry into its parent if a name different from its current one isn't provided
- Move a file to a path occupied by a directory or move a directory to a path occupied by a file
- Move any element to a path occupied by a directory that is not empty.
void moveTo ( in DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback );
Parameter
- parent
- The directory to which to move the entry.
- newName
- The new name of the entry. If you do not specify a name, the browser preserves the entry's current name.
- successCallback
- A callback that is called when the file or directory has been successfully moved.
- errorCallback
- An optional callback that is called only when errors happen.
Returns
void
copyTo()
Copy an entry to a different location on the file system. You cannot copy an entry inside itself if it is a directory, nor can you copy it into its parent if you don't provide a new name. Directory copies are always recursive—that is, they copy all contents of the directory. You cannot change this behavior. Files are simply duplicated.
void copyTo ( in DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback );
Parameter
- parent
- The directory where you want the entry to move to.
- newName
- The new name of the entry. If you do not specify a name, the browser preserves the entry's current name.
- successCallback
- A callback that is called when the file or directory has been successfully copied.
- errorCallback
- An optional callback that is called only when errors happen.
Returns
void
toURL()
Returns a URL that can be used to identify this entry. It exposes a new URL scheme—filesystem:—that you can use to fill src or href attributes. For example, if you wanted to display an image and have its fileEntry, calling toURL() gives you the image file's file system URL. You get something like: filesystem:https://example.com/temporary/lolcat.png.
The following is an example:
var img = document.createElement('img');
// Get the URL of the entry, which returns: filesystem:https://example.com/temporary/lolcat.png
img.src = fileEntry.toURL();
document.body.appendChild(img);
The file system URL does not expire. Because the method describes a location on disk, the URL is valid for as long as that location exists. You can delete the file and recreate it, and it's all good.
You can supply the mimeType to simulate the optional MIME-type header associated with HTTP downloads.
DOMString toURL ( in optional DOMString mimeType );
Parameter
- mimeType
- The MIME type that you want to be used to interpret the file when it is loaded through this URL.
Returns
DOMString
remove()
Deletes a file or directory. You cannot delete an empty directory or the root directory of a file system. If you want to remove an empty directory, use removeRecursively() instead.
void remove ( in VoidCallback successCallback, optional ErrorCallback errorCallback );
Parameter
- successCallback
- A callback that is called when the file is successfully deleted.
- errorCallback
- An optional callback that is called only when errors happen.
Returns
void
getParent()
Look up the parent DirectoryEntry containing the entry. If this entry is the root of its file system, then the parent is itself.
void getParent ( in EntryCallback successCallback, optional ErrorCallback errorCallback );
Parameter
- parent
- The directory where you want to move the entry.
- newName
- The new name of the entry. If you do not specify a name, the browser preserves the entry's current name.
- successCallback
- A callback that is called when the look-up entry is successful.
- errorCallback
- An optional callback that is called when errors happen.
Returns
void
Specifications
| Specification | Status | Comment |
|---|---|---|
| {{SpecName('File System API')}} | {{Spec2('File System API')}} | Draft of proposed API |
This API has no official W3C or WHATWG specification.
Browser compatibility
| Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
|---|---|---|---|---|---|
| Basic support | 13 {{property_prefix("webkit")}} | {{CompatGeckoDesktop(50)}}[1] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
copyTo(), getMetadata(), getParent(), moveTo(), remove(), toURL() |
13 {{property_prefix("webkit")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| filesystem: URL scheme | 13 {{property_prefix("webkit")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Basic support | {{CompatNo}} | 0.16 {{property_prefix("webkit")}} | {{CompatGeckoMobile(50)}}[1] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
copyTo(), getMetadata(), getParent(), moveTo(), remove(), toURL() |
{{CompatNo}} | 0.16 {{property_prefix("webkit")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
filesystem: URL scheme |
{{CompatNo}} | 0.16 {{property_prefix("webkit")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
[1] In Firefox, the error callback's parameter is a {{domxref("DOMError")}} rather than a {{domxref("FileError")}} object.