Skip to content

Latest commit

 

History

History
119 lines (100 loc) · 4.33 KB

EXPLAINER.md

File metadata and controls

119 lines (100 loc) · 4.33 KB
Raw

Directory Upload

Abstract

The Google Chrome team proposed and implemented a sandboxed file system API, defining a new storage type available to script, partitioned by origin. This API included types for creating, reading and writing files, as well as enumerating directories and accessing the files contained therein. The same directory enumeration types were made available to script when files and directories were dragged onto a page via the input element and Data Transfer mechanisms defined in HTML.

While the sandboxed file system API proposal has not been adopted by other browser vendors and is not widely used, the subset of the API supporting "directory upload" scenarios has been identified that other browser vendors may implement. This specification attempts to document the subset to allow the creation of interoperable implementations.

Previous Work

The File API: Directories and System specification (which is now a W3C Working Group Note) described the behavior of the sandboxed filesystem behavior in Chrome and the directory enumeration behavior methods and types at a high level. The most recent Editors Draft of the specification contains the full text of the proposal.

The Directory Upload proposal specifies a way to allow directory upload via HTML input elements, and methods and types for enumerating directory contents, but is not based on the behavior implemented in Google Chrome.

Goals

The goal of this document is to specify the existing behavior of Google Chrome necessary to create an interoperable implementation supporting script access to the contents of directories made available to the page by user actions such as form selection and drag-and-drop operations.

Where possible, this document will attempt to describe the behavior of the implemented API in a forward-looking, content-compatible manner. For example, previous descriptions used obsolete Web IDL constructs such as T[] to describe iterable collections of typed objects; the similar syntax sequence<T> and FrozenArray<T> will be used which may not have identical semantics but which are believed to be compatible with deployed content.

It is not a goal of this document to modify the described API in content-incompatible ways or improve the usability of the API; for example the script API contains several methods that accept success and error callback pairs. Newer web standards use the ECMAScript Promise type. This document does not propose changes to the methods to drop the callbacks and instead return Promises.

Finally, it is also very explicitly not a goal of this document to preclude further exploration of this area with APIs by other specifications that may improve the usability of this functionality. Directory Upload is an example of work that is soliciting feedback from browser implementors and web developers and may produce a more usable API.

Code Samples

Handle Drag-and-Drop

elem.addEventListener('drop', e => {
  e.preventDefault();
  for (let item of e.dataTransfer.items) {
    if (item.kind === 'file') {
      let entry = item.webkitGetAsEntry();
      handleEntry(entry);
    }
  }
});

Inspect an Entry

function handleEntry(entry) {
  console.log('name: ' + entry.name);
  console.log('path: ' + entry.fullPath);
  if (entry.isFile) {
    console.log('... is a file');
  } else if (entry.isDirectory) {
    console.log('... is a directory');
  }
}

Enumerate a Directory Entry

let reader = dirEntry.createReader();
let readBatch = function() {
    reader.readEntries(entries => {
      if (entries.length === 0) {
        return;
      }
      entries.forEach(handleEntry);
      readBatch();
    }, error => console.warn(error));
  };
readBatch();

Other Tutorials