在此页

• 关于本文档
• 概述
• Big concepts
• 限定
• Definitions
• 规范
• 浏览器兼容性
• 另请参阅
• 相关话题

非标
此特征是非标准的，且不在标准轨道中。不要在面向 Web 的生产站点中使用它：它不适用于每个用户。实现之间可能存在大的不兼容性，且行为将来可能改变。

文件和目录条目 API simulates a local file system that web apps can navigate around. You can develop apps that can read, write, and create files and directories in a sandboxed, virtual file system.

The File and Directory Entries API interacts with other related APIs. It was built on the File Writer API, which, in turn, was built on File API. Each of the APIs adds different functionality. These APIs are a giant evolutionary leap for web apps, which can now cache and process large amounts of data.

关于本文档

This introduction discusses essential concepts and terminology in the File and Directory Entries API. It gives you the big picture and orients you to key concepts . It also describes restrictions that raise security errors if you ignore them. To learn more about terminology used in this API, see the Definitions 章节。

For the reference documentation on the File and Directory Entries API, see the reference landing page and its subpages.

The specification is still being defined and is subject to change.

概述

The File and Directory Entries API includes both asynchronous and synchronous versions of the interfaces. The asynchronous API can be used in cases where you don't want an outstanding operation to block the UI. The synchronous API, on the other hand, allows for simpler programming model, but it must be used with WebWorkers .

Usefulness of the API

The File and Directory Entries API is an important API for the following reasons:

• It lets apps have offline and storage features that involve large binary blobs.
• It can improve performance by letting an app pre-fetch assets in the background and cache locally.
• It lets users of your web app directly edit a binary file that's in their local file directory.
• It provides a storage API that is already familiar to your users, who are used to working with file systems.

For examples of features you can create with this app, see the Sample use cases 章节。

The File and Directory Entries API and other storage APIs

The File and Directory Entries API is an alternative to other storage APIs like IndexedDB , WebSQL (which has been deprecated since November18, 2010), and AppCache. The API is a better choice for apps that deal with blobs for the following reasons:

• The File and Directory Entries API offers client-side storage for use cases that are not addressed by databases. If you want to have large mutable chunks of data, the File and Directory Entries API is a much more efficient storage solution than a database.
• While Firefox supports blob storage for IndexedDB, Chrome currently does not (Chrome is still implementing support for blob storage in IndexedDB). If you are targeting Chrome for your app and you want to store blobs, the File and Directory Entries API and App Cache are your only choices. However, AppCache storage isn't locally mutable, and doesn't allow for fine-grained client-side management.
• In Chrome, you can use the File and Directory Entries API with the Quota Management API , which lets you ask for more storage and manage your storage quota.

Sample use cases

The following are just a few examples of how you can use the File and Directory Entries API:

• Apps with persistent uploader
  • When a file or directory is selected for upload, you can copy the file into a local sandbox and upload a chunk at a time.
  • The app can restart uploads after an interruption, such as the browser being closed or crashing, connectivity getting interrupted, or the computer getting shut down.
• Video game or other apps with lots of media assets
  • The app downloads one or several large tarballs and expands them locally into a directory structure.
  • The app pre-fetches assets in the background, so the user can go to the next task or game level without waiting for a download.
• Audio or photo editor with offline access or local cache (great for performance and speed)
  • The app can write to files in place (for example, overwriting just the ID3/EXIF tags and not the entire file).
• Offline video viewer
  • The app can download large files (>1GB) for later viewing.
  • The app can access partially downloaded files (so that you can watch the first chapter of your DVD, even if the app is still downloading the rest of the content or if the app didn't complete the download because you had to run to catch a train).
• Offline web mail client
  • The client downloads attachments and stores them locally.
  • The client caches attachments for later upload.

Big concepts

Before you start using the File and Directory Entries API, you need to understand a few concepts:

• The File and Directory Entries API is a virtual representation of a file system
• The File and Directory Entries API can use different storage types
• Browsers impose storage quota
• The File and Directory Entries API has asynchronous and synchronous versions
• When using the asynchronous API, always use the error callbacks
• The File and Directory Entries API interacts with other APIs
• The File and Directory Entries API is case-sensitive

The File and Directory Entries API is a virtual representation of a file system

The API doesn't give you access to the local file system, nor is the sandbox really a section of the file system. Instead, it is a virtualized file system that looks like a full-fledged file system to the web app. It does not necessarily have a relationship to the local file system outside the browser.

What this means is that a web app and a desktop app cannot share the same file at the same time. The API does not let your web app reach outside the browser to files that desktop apps can also work on. You can, however, export a file from a web app to a desktop app. For example, you can use the File API, create a blob, redirect an iframe to the blob, and invoke the download manager.

The File and Directory Entries API can use different storage types

An application can request temporary or persistent storage. Temporary storage is easier to get, because the browser just gives it to you, but it is limited and can be deleted by the browser when it runs out of space. Persistent storage, on the other hand, might offer you larger space that can only be deleted by the user, but it requires the user to grant you permission.

Use temporary storage for caching and persistent storage for data that you want your app to keep—such as user-generated or unique data.

Browsers impose storage quotas

To prevent a web app from using up the entire disk, browsers might impose a quota for each app and allocate storage among web apps.

How storage space is granted or allocated and how you can manage storage are idiosyncratic to the browser, so you need to check the respective documentation of the browser. Google Chrome, for example, allows temporary storage beyond the 5 MB required in the specifications and supports the Quota Management API. To learn more about the Chrome-specific implementation, see Managing HTML5 Offline Storage .

The File and Directory Entries API has asynchronous and synchronous versions

The File and Directory Entries API comes with asynchronous and synchronous versions. Both versions of the API offer the same capabilities and features. In fact, they are almost alike, except for a few differences.

• WebWorkers. The asynchronous API can be used in either the document or WebWorkers context, while the synchronous API is for use with WebWorkers only.
• 回调 . The asynchronous API doesn't give you data by returning values; instead, you have to pass a callback function. You send requests for operations to happen, and get notified by callbacks. In contrast, the synchronous API does not use callbacks because the API methods return values.
• Global methods of the asynchronous and synchronous APIs . The asynchronous API has the following global methods: requestFileSystem() and resolveLocalFileSystemURL() . These methods are members of both the window object and the worker global scope. The synchronous API, on the other hand, uses the following methods: requestFileSystemSync() and resolveLocalFileSystemSyncURL() . These synchronous methods are members of the worker's global scope only, not the window object.

The synchronous API can be simpler for some tasks. Its direct, in-order programming model can make code easier to read. The drawback of synchronous API has to do with its interactions with Web Workers, which has some limitations.

When using the asynchronous API, always use the error callbacks

When using the asynchronous API, always use the error callbacks. Although the error callbacks for the methods are optional parameters, they are not optional for your sanity. You want to know why your calls failed. At minimum, handle the errors to provide error messages, so you'll have an idea of what's going on.

The File and Directory Entries API interacts with other APIs

The File and Directory Entries API is designed to be used with other APIs and elements on the web platform. For example, you are likely to use one of the following:

• XMLHttpRequest (such as the send() method for file and blob objects)
• Drag and Drop API
• Web Workers (for the synchronous version of the File and Directory Entries API)
• input element (to programmatically obtain a list of files from the element)

The File and Directory Entries API is case sensitive

The filesystem API is case-sensitive, and case-preserving.

限定

For security reasons, browsers impose restrictions on file access. If you ignore them, you will get security errors.

• The File and Directory Entries API adheres to the same-origin policy
• The File and Directory Entries API does not let you create and rename executable files
• The file system is sandboxed
• You cannot run your app from file://

The File and Directory Entries API adheres to the same-origin policy

An origin is the domain, application layer protocol, and port of a URL of the document where the script is being executed. Each origin has its own associated set of file systems.

The security boundary imposed on file system prevents applications from accessing data with a different origin. This protects private data by preventing access and deletion. For example, while an app or a page in http://www.example.com/app/ can access files from http://www.example.com/dir/ , because they have the same origin, it cannot retrieve files from http://www.example.com:8080/dir/ (different port) or https://www.example.com/dir/ (different protocol).

The File and Directory Entries API does not let you create and rename executable files

To prevent malicious apps from running hostile executables, you cannot create executable files within the sandbox of the File and Directory Entries API.

The file system is sandboxed

Because the file system is sandboxed, a web app cannot access another app's files. You also cannot read or write files to an arbitrary folder (for example, My Pictures and My Documents) on the user's hard drive.

You cannot run your app from file://

You cannot run your app locally from file:// . If you do so, the browser throws errors or your app fails silently. This restriction also applies to many of the file APIs, including BlobBuilder and FileReader.

For testing purposes, you can bypass the restriction on Chrome by starting the browser with the --allow-file-access-from-files flag. Use this flag only for this purpose.

Definitions

This section defines and explains terms used in the File and Directory Entries API.

blob

Stands for binary large object. A blob is a set of binary data that is stored as a single object. It is a general-purpose way to reference binary data in web applications. A blob can be an image or an audio file.

Blob

Blob—with a capital B—is a data structure that is immutable, which means that binary data referenced by a Blob cannot be modified directly. This makes Blobs act predictably when they are passed to asynchronous APIs.

persistent storage

Persistent storage is storage that stays in the browser unless the user expunges it or the app deletes it.

temporary storage

Transient storage is available to any web app. It is automatic and does not need to be requested, but the browser can delete the storage without warning.

规范

规范	状态	注释
文件和目录条目 API	草案	提议 API 草案

此 API 没有正式的 W3C 或 WHATWG (Web 超文本应用程序技术工作组) 规范。

浏览器兼容性

FileSystem

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
FileSystem	Chrome 7 Alternate Name 7 Alternate Name Alternate Name Uses the non-standard name: DOMFileSystem	Edge ≤18 Prefixed ≤18 Prefixed 注意事项 Prefixed Implemented with the vendor prefix: WebKit 注意事项 Edge only supports this API in drag-and-drop scenarios using the the DataTransferItem.webkitGetAsEntry() method. It's not available for use in file or folder picker panels (such as when you use an <input> element with the HTMLInputElement.webkitdirectory 属性。	Firefox 50	IE 不支持 No	Opera 15 Prefixed 15 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari 11.1	WebView Android ≤37 Alternate Name ≤37 Alternate Name Alternate Name Uses the non-standard name: DOMFileSystem	Chrome Android 18 Alternate Name 18 Alternate Name Alternate Name Uses the non-standard name: DOMFileSystem	Firefox Android 50	Opera Android 14 Prefixed 14 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari iOS 11.3	Samsung Internet Android 1.0 Prefixed 1.0 Prefixed Prefixed Implemented with the vendor prefix: webkit

图例

完整支持

完整支持

不支持

不支持

见实现注意事项。

见实现注意事项。

使用非标名称。

使用非标名称。

要求使用供应商前缀或不同名称。

要求使用供应商前缀或不同名称。

FileSystemSync property

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
FileSystemSync 非标	Chrome 13 Prefixed 13 Prefixed Prefixed Implemented with the vendor prefix: webkit	Edge ≤79 Prefixed ≤79 Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox 不支持 No	IE 不支持 No	Opera 15 Prefixed 15 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari 6 Prefixed 6 Prefixed Prefixed Implemented with the vendor prefix: webkit	WebView Android ≤37 Prefixed ≤37 Prefixed Prefixed Implemented with the vendor prefix: webkit	Chrome Android 18 Prefixed 18 Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox Android 不支持 No	Opera Android 14 Prefixed 14 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari iOS 6 Prefixed 6 Prefixed Prefixed Implemented with the vendor prefix: webkit	Samsung Internet Android 1.0 Prefixed 1.0 Prefixed Prefixed Implemented with the vendor prefix: webkit

图例

完整支持

不支持

不支持

非标。预期跨浏览器支持较差。

非标。预期跨浏览器支持较差。

要求使用供应商前缀或不同名称。

要求使用供应商前缀或不同名称。

另请参阅

• 文件和目录条目 API
• Exploring the FileSystem APIs (HTML5 Rocks)

元数据

• 最后修改： Oct 24, 2019

相关话题

1. 文件和目录条目 API
2. 指南

   1. 文件和目录条目 API 介绍
   2. Firefox 中的文件和目录条目 API 支持
3. 接口

   1. FileError
   2. FileException
   3. FileHandle
   4. FileRequest
   5. FileSystemDirectoryEntry
   6. FileSystemDirectoryEntrySync
   7. FileSystemDirectoryReader
   8. FileSystemDirectoryReaderSync
   9. FileSystemEntry
   10. FileSystemEntrySync
   11. FileSystemFileEntry
   12. FileSystemFileEntrySync
   13. FileSystemFlags
   14. FileSystem
   15. FileSystemSync
   16. HTMLInputElement
   17. LocalFileSystem
   18. LocalFileSystemSync
   19. LockedFile
   20. 元数据
4. 方法

   1. Window.requestFileSystem()
   2. Window.resolveLocalFileSystemURL()
   3. WorkerGlobalScope.requestFileSystemSync()