File API

1. 引言

本节是资料性的。

Web 应用应具备处理尽可能广泛的用户输入的能力，包括用户希望上传到远程服务器或在丰富的 Web 应用中操作的文件。本规范定义了文件的基本表示形式、文件列表、因访问文件而引发的错误，以及读取文件的编程方式。此外，本规范还定义了一个接口，用于表示可以在符合要求的用户代理的主线程上异步处理的“原始数据”。本规范中定义的接口和 API 可以与暴露给 Web 平台的其他接口和 API 一起使用。

File 接口表示通常从底层文件系统获取的文件数据，而 Blob 接口（“二进制大对象”——一个最初在 Google Gears 中引入到 Web API 的名称）表示不可变的原始数据。File 或 Blob 读取应在主线程上异步进行，并在线程化的 Web 应用中使用可选的同步 API。用于读取文件的异步 API 可以防止阻塞用户代理的主线程并导致 UI“冻结”。本规范定义了一个基于 *事件模型* 的异步 API，用于读取和访问 File 或 Blob 的数据。FileReader 对象提供异步读取方法，通过事件处理器内容属性和触发事件来访问该文件的数据。事件和事件处理器的使用允许独立的代码块监控 *读取进度*（这对远程驱动器或挂载驱动器特别有用，因为这些驱动器的文件访问性能可能与本地驱动器不同）以及在读取文件过程中可能出现的错误状况。一个示例将有助于说明。

function startRead() {
  // obtain input element through DOM

  var file = document.getElementById('file').files[0];
  if(file){
    getAsText(file);
  }
}

function getAsText(readFile) {

  var reader = new FileReader();

  // Read file into memory as UTF-16
  reader.readAsText(readFile, "UTF-16");

  // Handle progress, success, and errors
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

function updateProgress(evt) {
  if (evt.lengthComputable) {
    // evt.loaded and evt.total are ProgressEvent properties
    var loaded = (evt.loaded / evt.total);
    if (loaded < 1) {
      // Increase the prog bar length
      // style.width = (loaded * 200) + "px";
    }
  }
}

function loaded(evt) {
  // Obtain the read file data
  var fileString = evt.target.result;
  // Handle UTF-16 file dump
  if(utils.regexp.isChinese(fileString)) {
    //Chinese Characters + Name validation
  }
  else {
    // run other charset test
  }
  // xhr.send(fileString)
}

function errorHandler(evt) {
  if(evt.target.error.name == "NotReadableError") {
    // The file could not be read
  }
}

2. 术语与算法

当本规范提到终止算法时，用户代理必须在完成当前步骤后终止该算法。本规范中定义的异步 读取方法 可能会在该算法终止之前返回，并可以通过 abort() 调用来终止。

本规范中的算法和步骤使用以下数学运算

• max(a,b) 返回 a 和 b 中的最大值，并且始终对整数执行，正如 WebIDL [WebIDL] 中定义的那样；例如 max(6,4) 的结果为 6。此操作也定义在 ECMAScript [ECMA-262] 中。

• min(a,b) 返回 a 和 b 中的最小值，并且始终对整数执行，正如 WebIDL [WebIDL] 中定义的那样；例如 min(6,4) 的结果为 4。此操作也定义在 ECMAScript [ECMA-262] 中。

• 数学比较（如 <（小于）、≤（小于或等于）和 >（大于））与 ECMAScript [ECMA-262] 中的定义相同。

术语 Unix 纪元（Unix Epoch） 在本规范中用于指代 1970 年 1 月 1 日 00:00:00 UTC（或 1970-01-01T00:00:00Z ISO 8601）的时间；这与 ECMA-262 [ECMA-262] 中概念上的“0”时间相同。

3. Blob 接口与二进制数据

Blob 对象指代一个 字节 序列，并具有一个 size 属性（它是字节序列中的总字节数）和一个 type 属性（它是以 ASCII 编码的小写字符串，表示 字节 序列的媒体类型）。

每个 Blob 必须具有一个内部的 快照状态（snapshot state），如果存在任何此类底层存储，它必须初始设置为底层存储的状态。关于 快照状态 的进一步规范定义可以在 File 中找到。

[Exposed=(Window,Worker), Serializable]
interface Blob {
  constructor(optional sequence<BlobPart> blobParts,
              optional BlobPropertyBag options = {});

  readonly attribute unsigned long long size;
  readonly attribute DOMString type;

  // slice Blob into byte-ranged chunks
  Blob slice(optional [Clamp] long long start,
            optional [Clamp] long long end,
            optional DOMString contentType);

  // read from the Blob.
  [NewObject] ReadableStream stream();
  [NewObject] Promise<USVString> text();
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] Promise<Uint8Array> bytes();
};

enum EndingType { "transparent", "native" };

dictionary BlobPropertyBag {
  DOMString type = "";
  EndingType endings = "transparent";
};

typedef (BufferSource or Blob or USVString) BlobPart;

Blob 对象是 可序列化对象。给定 value 和 serialized，其 序列化步骤 为：

1. 将 serialized.[[SnapshotState]] 设置为 value 的 快照状态。

2. 将 serialized.[[ByteSequence]] 设置为 value 的底层字节序列。

给定 serialized 和 value，其 反序列化步骤 为：

1. 将 value 的 快照状态 设置为 serialized.[[SnapshotState]]。

2. 将 value 的底层字节序列设置为 serialized.[[ByteSequence]]。

3.1. 构造函数

3.1.1. 构造函数参数

Blob() 构造函数可以使用以下参数调用：

一个 blobParts 序列（sequence）

它接受任意数量的以下类型的元素，并且顺序不限：

• BufferSource 元素。

• Blob 元素。

• USVString 元素。

一个 可选的 BlobPropertyBag

它接受这些可选成员：

• type，表示 Blob 媒体类型的以 ASCII 编码的小写字符串。该成员的规范条件在 § 3.1 构造函数 中提供。

• endings，一个枚举，可取值 "transparent" 或 "native"。默认情况下设置为 "transparent"。如果设置为 "native"，blobParts 中的任何 USVString 元素中的 换行符将被转换为原生格式。

// Create a new Blob object

var a = new Blob();

// Create a 1024-byte ArrayBuffer
// buffer could also come from reading a File

var buffer = new ArrayBuffer(1024);

// Create ArrayBufferView objects based on buffer

var shorts = new Uint16Array(buffer, 512, 128);
var bytes = new Uint8Array(buffer, shorts.byteOffset + shorts.byteLength);

var b = new Blob(["foobarbazetcetc" + "birdiebirdieboo"], {type: "text/plain;charset=utf-8"});

var c = new Blob([b, shorts]);

var a = new Blob([b, c, bytes]);

var d = new Blob([buffer, b, c, bytes]);

3.2. 属性

size， 类型为 unsigned long long，只读

返回字节序列的大小（以字节为单位）。在获取时，符合要求的用户代理必须返回可由 FileReader 或 FileReaderSync 对象读取的总字节数；如果 Blob 没有可读取的字节，则返回 0。

type， 类型为 DOMString，只读

以 ASCII 编码的小写字符串，表示 Blob 的媒体类型。在获取时，用户代理必须将 Blob 的类型作为 ASCII 编码的小写字符串返回，使得当其转换为 字节 序列时，它是一个 可解析的 MIME 类型；或者，如果类型无法确定，则返回空字符串（0 字节）。

type 属性可以由 Web 应用本身通过构造函数调用和 slice() 调用设置；在这些情况下，该属性的进一步规范条件分别在 § 3.1 构造函数、§ 4.1 构造函数 和 § 3.3.1 slice() 方法 中。用户代理也可以确定 Blob 的 type，特别是如果 字节 序列来自磁盘文件；在这种情况下，进一步的规范条件在 文件类型指南 中。

注意：如果对从表示 Blob 对象类型的 ASCII 编码字符串转换而来的字节序列执行 解析 MIME 类型 算法不返回失败，则 Blob 的类型 t 被视为 可解析的 MIME 类型。

注意：type 属性的使用会通知 包装数据（package data） 算法，并在 获取（fetching） blob URL 时确定 Content-Type 标头。

3.3. 方法与参数

3.3.1. slice() 方法

// obtain input element through DOM

var file = document.getElementById('file').files[0];
if(file)
{
  // create an identical copy of file
  // the two calls below are equivalent

  var fileClone = file.slice();
  var fileClone2 = file.slice(0, file.size);

  // slice file into 1/2 chunk starting at middle of file
  // Note the use of negative number

  var fileChunkFromEnd = file.slice(-(Math.round(file.size/2)));

  // slice file into 1/2 chunk starting at beginning of file

  var fileChunkFromStart = file.slice(0, Math.round(file.size/2));

  // slice file from beginning till 150 bytes before end

  var fileNoMetadata = file.slice(0, -150, "application/experimental");
}

3.3.2. stream() 方法

stream() 方法在调用时，必须返回对 this 调用 获取流（get stream） 的结果。

3.3.3. text() 方法

text() 方法在调用时，必须运行这些步骤：

1. 令 stream 为对 this 调用 获取流 的结果。

2. 令 reader 为从 stream 获取读取器（getting a reader） 的结果。如果这抛出了异常，则返回一个被该异常拒绝的新 Promise。

3. 令 promise 为使用 reader 从 stream 读取所有字节（reading all bytes） 的结果。

4. 返回通过一个 fulfillment 处理程序转换 promise 的结果，该处理程序返回对其第一个参数运行 UTF-8 解码 的结果。

注意：这与 readAsText() 的行为不同，以便更好地与 Fetch 的 text() 行为保持一致。具体而言，此方法将始终使用 UTF-8 作为编码，而 FileReader 可以根据 blob 的类型和传入的编码名称使用不同的编码。

3.3.4. arrayBuffer() 方法

arrayBuffer() 方法在调用时，必须运行这些步骤：

1. 令 stream 为对 this 调用 获取流 的结果。

2. 令 reader 为从 stream 获取读取器 的结果。如果这抛出了异常，则返回一个被该异常拒绝的新 Promise。

3. 令 promise 为使用 reader 从 stream 读取所有字节 的结果。

4. 返回通过一个 fulfillment 处理程序转换 promise 的结果，该处理程序返回一个内容为该 fulfillment 处理程序第一个参数的新 ArrayBuffer。

3.3.5. bytes() 方法

bytes() 方法在调用时，必须运行这些步骤：

1. 令 stream 为对 this 调用 获取流 的结果。

2. 令 reader 为从 stream 获取读取器 的结果。如果这抛出了异常，则返回一个被该异常拒绝的新 Promise。

3. 令 promise 为使用 reader 从 stream 读取所有字节 的结果。

4. 返回通过一个 fulfillment 处理程序转换 promise 的结果，该处理程序返回一个包装了包含其第一个参数的 ArrayBuffer 的新 Uint8Array。

4. File 接口

File 对象是一个带有 name 属性的 Blob 对象（该属性为字符串）；它可以通过构造函数在 Web 应用中创建，或者是指代来自底层（OS）文件系统的文件 字节 序列的引用。

如果 File 对象是指代源自磁盘文件的 字节 序列的引用，则其 快照状态 应设置为 File 对象创建时磁盘上文件的状态。

注意：对于用户代理而言，这是一项非平凡的实现需求，因此这不是一项 *必须（must）* 而是 *应该（should）* [RFC2119] 的要求。用户代理应努力使 File 对象的 快照状态 在获取引用时设置为底层存储在磁盘上的状态。如果在获取引用后文件在磁盘上被修改，则 File 的 快照状态 将与底层存储的状态不同。用户代理可以使用修改时间戳和其他机制来维持 快照状态，但这留作实现细节。

当 File 对象指代磁盘上的文件时，用户代理必须返回该文件的 type，并且必须遵循下方的 文件类型指南（file type guidelines）：

• 用户代理必须将 type 作为以 ASCII 编码的小写字符串返回，使得当其转换为相应的字节序列时，它是一个 可解析的 MIME 类型；或者，如果类型无法确定，则为空字符串（0 字节）。

• 当文件类型为 text/plain 时，用户代理不得在媒体类型的 参数字典（dictionary of parameters） 部分追加 charset 参数 [MIMESNIFF]。

• 用户代理不得尝试启发式确定编码，包括统计方法。

[Exposed=(Window,Worker), Serializable]
interface File : Blob {
  constructor(sequence<BlobPart> fileBits,
              USVString fileName,
              optional FilePropertyBag options = {});
  readonly attribute DOMString name;
  readonly attribute long long lastModified;
};

dictionary FilePropertyBag : BlobPropertyBag {
  long long lastModified;
};

File 对象是 可序列化对象。给定 value 和 serialized，其 序列化步骤 为：

1. 将 serialized.[[SnapshotState]] 设置为 value 的 快照状态。

2. 将 serialized.[[ByteSequence]] 设置为 value 的底层字节序列。

3. 将 serialized.[[Name]] 设置为 value 的 name 属性的值。

4. 将 serialized.[[LastModified]] 设置为 value 的 lastModified 属性的值。

给定 value 和 serialized，其 反序列化步骤 为：

1. 将 value 的 快照状态 设置为 serialized.[[SnapshotState]]。

2. 将 value 的底层字节序列设置为 serialized.[[ByteSequence]]。

3. 将 value 的 name 属性的值初始化为 serialized.[[Name]]。

4. 将 value 的 lastModified 属性的值初始化为 serialized.[[LastModified]]。

4.1. 构造函数

4.1.1. 构造函数参数

File() 构造函数可以使用以下参数调用：

一个 fileBits 序列（sequence）

它接受任意数量的以下元素，并且顺序不限：

BufferSource 元素。

Blob 元素（包括 File 元素）。

USVString 元素。

一个 fileName 参数

一个表示文件名的 USVString 参数；此构造函数参数的规范条件可在 § 4.1 构造函数 中找到。

一个可选的 FilePropertyBag 字典

它除了 BlobPropertyBag 的 成员 外，还接受一个成员：

一个可选的 lastModified 成员，它必须是 long long 类型；此成员的规范条件在 § 4.1 构造函数 中提供。

4.2. 属性

name， 类型为 DOMString，只读

文件名。在获取时，这必须返回作为字符串的文件名。不同的底层操作系统文件系统使用了众多的文件名变体和约定；这仅仅是文件名，不包含路径信息。在获取时，如果用户代理无法使此信息可用，则必须返回空字符串。如果 File 对象是使用构造函数创建的，则该属性的进一步规范条件可在 § 4.1 构造函数 中找到。

lastModified， 类型为 long long，只读

文件的最后修改日期。在获取时，如果用户代理可以使此信息可用，则必须返回一个 long long，设置为文件最后一次修改的时间，即自 Unix 纪元 以来的毫秒数。如果最后修改日期和时间未知，则该属性必须返回当前日期和时间作为代表自 Unix 纪元 以来的毫秒数的 long long 值；这等同于 Date.now() [ECMA-262]。如果 File 对象是使用构造函数创建的，则该属性的进一步规范条件可在 § 4.1 构造函数 中找到。

File 接口在暴露类型为 FileList 属性的对象上可用；这些对象在 HTML [HTML] 中定义。File 接口继承自 Blob，它是不可变的，因此表示在启动 读取操作 时可以读入内存的文件数据。用户代理必须将那些在读取时已不存在的文件的读取处理为 错误，如果在 Web Worker [Workers] 上使用 FileReaderSync，则抛出 NotFoundError 异常；或者触发一个带有 error 属性（返回 NotFoundError）的 错误 事件。

5. The FileList Interface

注意：FileList 接口应被视为“有风险”，因为 Web 平台的总体趋势是将此类接口替换为 ECMAScript [ECMA-262] 中的 Array 平台对象。特别是，这意味着 filelist.item(0) 这种语法是有风险的；FileList 的大多数其他编程使用不太可能受到最终迁移到 Array 类型的影响。

此接口是 File 对象的列表。

[Exposed=(Window,Worker), Serializable]
interface FileList {
  getter File? item(unsigned long index);
  readonly attribute unsigned long length;
};

FileList 对象是 可序列化对象。给定 value 和 serialized，其 序列化步骤 为：

1. 将 serialized.[[Files]] 设置为一个空 列表。

2. 对于 value 中的每个 file，将 file 的 子序列化（sub-serialization） 追加到 serialized.[[Files]] 中。

给定 serialized 和 value，其 反序列化步骤 为：

1. 对于 serialized.[[Files]] 中的每个 file，将 file 的 子反序列化（sub-deserialization） 添加到 value 中。

5.1. 属性

length， 类型为 unsigned long，只读

必须返回 FileList 对象中的文件数量。如果没有文件，该属性必须返回 0。

5.2. 方法与参数

item(index)

必须返回 FileList 中的第 index 个 File 对象。如果 FileList 中不存在第 index 个 File 对象，则该方法必须返回 null。index 必须由用户代理视为 FileList 中 File 对象位置的值，0 表示第一个文件。支持的属性索引（Supported property indices） 是范围从 0 到由 FileList 对象表示的 File 对象数量减 1 的数字。如果没有此类 File 对象，则没有支持的属性索引。

注意：HTMLInputElement 接口具有一个类型为 FileList 的只读属性，这就是上述示例中正在访问的内容。其他具有类型为 FileList 的只读属性的接口包括 DataTransfer 接口。

6. 读取数据

6.1. 文件读取任务源

本规范定义了一个新的通用 任务源（task source），称为 文件读取任务源（file reading task source），它用于本规范中所有 排队任务，以读取与 Blob 和 File 对象关联的字节序列。它应被用于响应异步读取二进制数据而触发的功能。

6.2. FileReader API

[Exposed=(Window,Worker)]
interface FileReader: EventTarget {
  constructor();
  // async read methods
  undefined readAsArrayBuffer(Blob blob);
  undefined readAsBinaryString(Blob blob);
  undefined readAsText(Blob blob, optional DOMString encoding);
  undefined readAsDataURL(Blob blob);

  undefined abort();

  // states
  const unsigned short EMPTY = 0;
  const unsigned short LOADING = 1;
  const unsigned short DONE = 2;

  readonly attribute unsigned short readyState;

  // File or Blob data
  readonly attribute (DOMString or ArrayBuffer)? result;

  readonly attribute DOMException? error;

  // event handler content attributes
  attribute EventHandler onloadstart;
  attribute EventHandler onprogress;
  attribute EventHandler onload;
  attribute EventHandler onabort;
  attribute EventHandler onerror;
  attribute EventHandler onloadend;
};

FileReader 具有一个关联的 状态（state），即 "empty"、"loading" 或 "done"。它最初为 "empty"。

FileReader 具有一个关联的 结果（result）（null、DOMString 或 ArrayBuffer）。它最初为 null。

FileReader 具有一个关联的 错误（error）（null 或 DOMException）。它最初为 null。

FileReader() 构造函数在调用时，必须返回一个新的 FileReader 对象。

readyState 属性的 getter 在调用时，切换 this 的 状态 并运行关联的步骤：

"empty"

返回 EMPTY

"loading"

返回 LOADING

"done"

返回 DONE

[Exposed=(DedicatedWorker,SharedWorker)]
interface FileReaderSync {
  constructor();
  // Synchronously return strings

  ArrayBuffer readAsArrayBuffer(Blob blob);
  DOMString readAsBinaryString(Blob blob);
  DOMString readAsText(Blob blob, optional DOMString encoding);
  DOMString readAsDataURL(Blob blob);
};

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partial interface URL {
  static DOMString createObjectURL((Blob or MediaSource) obj);
  static undefined revokeObjectURL(DOMString url);
};