ファイルとディレクトリエントリAPIの概要

この翻訳は不完全です。英語から この記事を翻訳 してください。

非標準
この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

ファイルとディレクトリエントリAPIは、Webアプリケーションがナビゲートできるローカルファイルシステムをシミュレートします。 サンドボックス化された仮想ファイルシステムでファイルやディレクトリの読み取り、書き込み、作成ができるアプリを開発できます。

ファイルおよびディレクトリエントリAPIは、他の関連APIと相互作用します。 これはFile Writer API上に構築され、File API上に構築されています。 各APIは異なる機能を追加します。 これらのAPIは、大量のデータをキャッシュして処理することができるWebアプリケーションの巨大な進歩的な飛躍です。

About this document

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 section. 

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.

Overview

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 section.  

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 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. 
  • Callbacks. 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)
  • The 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. 

 

Restrictions

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

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 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.

Specifications

Specification Status Comment
File and Directory Entries API ドラフト Draft of proposed API

This API has no official W3C or WHATWG specification.

Browser compatibility

FileSystem

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeEdge MobileAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
FileSystem
非推奨非標準
Chrome 完全対応 13
接頭辞付き
完全対応 13
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Edge 完全対応 あり
接頭辞付き 補足
完全対応 あり
接頭辞付き 補足
接頭辞付き 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 attribute.
Firefox 完全対応 50IE 未対応 なしOpera 完全対応 15
接頭辞付き
完全対応 15
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Safari 未対応 なしWebView Android ? Chrome Android ? Edge Mobile ? Firefox Android 完全対応 50Opera Android 完全対応 15
接頭辞付き
完全対応 15
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Safari iOS 未対応 なしSamsung Internet Android ?

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
非標準。ブラウザー間の互換性が低い可能性があります。
非標準。ブラウザー間の互換性が低い可能性があります。
非推奨。新しいウェブサイトでは使用しないでください。
非推奨。新しいウェブサイトでは使用しないでください。
実装ノートを参照してください。
実装ノートを参照してください。
使用するには、ベンダー接頭辞または異なる名前が必要です。
使用するには、ベンダー接頭辞または異なる名前が必要です。

FileSystemSync property

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeEdge MobileAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
FileSystemSync
非標準
Chrome 完全対応 13
接頭辞付き
完全対応 13
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Edge ? Firefox 未対応 なしIE 未対応 なしOpera 未対応 なしSafari 未対応 なしWebView Android 完全対応 あり
接頭辞付き
完全対応 あり
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Chrome Android 完全対応 あり
接頭辞付き
完全対応 あり
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Edge Mobile ? Firefox Android 未対応 なしOpera Android 未対応 なしSafari iOS 未対応 なしSamsung Internet Android ?

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
非標準。ブラウザー間の互換性が低い可能性があります。
非標準。ブラウザー間の互換性が低い可能性があります。
使用するには、ベンダー接頭辞または異なる名前が必要です。
使用するには、ベンダー接頭辞または異なる名前が必要です。

See also

ドキュメントのタグと貢献者

このページの貢献者: mdnwebdocs-bot, silverskyvicto
最終更新者: mdnwebdocs-bot,