File and Directory Entries API
The File and Directory Entries API provides a way to process directories and file lists provided by the user via a form input or a drag-and-drop operation. It is a more advanced version of the File API, which allows you to work with a single file. It was originally intended to support a full virtual file system, but now only supports read operations on user-provided data.
See Relationship to other file-related APIs for a comparison between this API, the File System API, and the File API.
Getting access to a file system
There are two ways to get access to file systems defined in the current specification draft:
- When handling a
drop
event for drag and drop, you can callDataTransferItem.webkitGetAsEntry()
to get theFileSystemEntry
for a dropped item. If the result isn'tnull
, then it's a dropped file or directory, and you can use file system calls to work with it. - The
HTMLInputElement.webkitEntries
property lets you access theFileSystemFileEntry
objects for the currently selected files, but only if they are dragged-and-dropped onto the file chooser (Firefox bug 1326031). IfHTMLInputElement.webkitdirectory
istrue
, the<input>
element is instead a directory picker, and you getFileSystemDirectoryEntry
objects for each selected directory.
History
The original File System API was created to let browsers implement support for accessing a sandboxed virtual file system on the user's storage device. Work to standardize the specification was abandoned back in 2012, but by that point, Google Chrome included its own implementation of the API. Over time, a number of popular sites and Web applications came to use it, often without providing any means of falling back to standard APIs or even checking to be sure the API is available before using it. Mozilla instead opted to implement other APIs which can be used to solve many of the same problems, such as IndexedDB; see the blog post Why no FileSystem API in Firefox? for more insights.
As a result, a number of popular websites did not work properly on browsers other than Chrome. To resolve that, the features of Google's API for which consensus could be reached were standardized as the File and Directory Entries API, and this was then implemented in other browsers.
Interfaces
The File and Directory Entries API includes the following interfaces:
FileSystem
-
Represents a file system.
FileSystemEntry
-
The basic interface representing a single entry in a file system. This is implemented by other interfaces which represent files or directories.
FileSystemFileEntry
-
Represents a single file in a file system.
FileSystemDirectoryEntry
-
Represents a single directory in a file system.
FileSystemDirectoryReader
-
Created by calling
FileSystemDirectoryEntry.createReader()
, this interface provides the functionality which lets you read the contents of a directory.
Extensions to other interfaces
DataTransferItem.webkitGetAsEntry()
-
Returns an object based on
FileSystemEntry
representing the selected file's entry in its file system. This will generally be either aFileSystemFileEntry
orFileSystemDirectoryEntry
object. File.webkitRelativePath
-
Returns the path the URL of the
File
is relative to. HTMLInputElement.webkitdirectory
-
A boolean that represents the
webkitdirectory
attribute. Iftrue
, the file-system-picker interface only accepts directories instead of files. HTMLInputElement.webkitEntries
-
Describes the currently selected files or directories.
Specifications
Specification |
---|
File and Directory Entries API # api-domfilesystem |