文件 API

1. 简介

本节为说明性内容。

Web 应用程序应具备操作尽可能多的用户输入类型的能力，包括用户可能希望上传到远程服务器或在富 Web 应用程序中操作的文件。 本规范定义了文件的基本表示、文件列表、文件访问产生的错误以及读取文件的编程方式。 此外，本规范还定义了一个表示“原始数据”的接口，该接口可以在符合标准的用户代理的主线程上异步处理。 本规范中定义的接口和 API 可与 Web 平台上公开的其他接口和 API 一起使用。

File 接口代表通常从底层文件系统获取的文件数据， Blob 接口 （“二进制大对象” - 最初由 Google Gears 引入到 Web API 中） 表示不可变的原始数据。File 或 Blob 的读取应在主线程上异步进行， 线程化 Web 应用程序中可使用可选的同步 API。 使用异步 API 读取文件可防止阻塞并避免用户代理的主线程“冻结”界面。 本规范定义了基于 事件模型 的异步 API，用于读取和访问 File 或 Blob 的数据。 FileReader 对象提供异步读取方法以访问文件的数据， 通过事件处理器内容属性和事件的触发来进行读取。 使用事件和事件处理器允许不同的代码块监视 读取进度（这在远程驱动器或挂载的驱动器中尤为有用，因为文件访问性能可能与本地驱动器不同）， 以及在读取文件时可能出现的错误情况。 下面的示例将更具说明性。

function startRead() {
  // 通过 DOM 获取 input 元素

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

function getAsText(readFile) {

  var reader = new FileReader();

  // 将文件作为 UTF-16 读取到内存中
  reader.readAsText(readFile, "UTF-16");

  // 处理进度、成功和错误
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

function updateProgress(evt) {
  if (evt.lengthComputable) {
    // evt.loaded 和 evt.total 是 ProgressEvent 属性
    var loaded = (evt.loaded / evt.total);
    if (loaded < 1) {
      // 增加进度条长度
      // style.width = (loaded * 200) + "px";
    }
  }
}

function loaded(evt) {
  // 获取读取的文件数据
  var fileString = evt.target.result;
  // 处理 UTF-16 文件转储
  if(utils.regexp.isChinese(fileString)) {
    // 中文字符 + 名称验证
  }
  else {
    // 运行其他字符集测试
  }
  // xhr.send(fileString)
}

function errorHandler(evt) {
  if(evt.target.error.name == "NotReadableError") {
    // 无法读取文件
  }
}

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 纪元 指的是 1970 年 1 月 1 日 00:00:00 UTC 的时间 （或 1970-01-01T00:00:00Z ISO 8601）； 这是 ECMA-262 中概念上 "0" 的时间 [ECMA-262]。

3. Blob 接口与二进制数据

Blob 对象 指的是一个 字节 序列， 并且有一个 大小 属性，表示字节序列中的字节总数， 以及一个 类型 属性， 这是一个小写的 ASCII 编码字符串，表示该 字节 序列的媒体类型。

每个 Blob 必须 有一个内部 快照状态， 如果存在底层存储，则该状态必须最初设置为底层存储的状态。 有关 快照状态 的进一步规范定义可以在 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 序列

它可以包含以下任意类型的元素，并且顺序不限：

• BufferSource 元素。

• Blob 元素。

• USVString 元素。

一个 可选的 BlobPropertyBag

它包含以下可选成员：

• type， 一个小写的 ASCII 编码字符串，表示 Blob 的媒体类型。 有关此成员的规范条件，请参阅 § 3.1 构造函数。

• endings， 一个枚举，值可以为 "transparent" 或 "native"。 默认情况下，此值设置为 "transparent"。 如果设置为 "native"， 则行结束符将被转换为本地格式 ，在 USVString 元素中转换。

// 创建一个新的 Blob 对象

var a = new Blob();

// 创建一个 1024 字节的 ArrayBuffer
// buffer 也可以来自读取一个文件

var buffer = new ArrayBuffer(1024);

// 基于 buffer 创建 ArrayBufferView 对象

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， 只读

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

type 属性可以通过构造函数调用或 slice() 调用由 Web 应用程序自行设置； 在这些情况下，此属性的进一步规范条件请参阅 § 3.1 构造函数、§ 4.1 构造函数 和 § 3.3.1 slice() 方法。 用户代理还可以确定 type 的 Blob， 特别是当字节序列来自磁盘文件时； 在这种情况下，进一步的规范条件请参阅 文件类型指南。

注意： 如果将表示 Blob 对象类型的 ASCII 编码字符串转换为字节序列时， 执行 解析 MIME 类型 算法没有返回失败， 则 t 类型的 Blob 被认为是 可解析的 MIME 类型。

注意： 使用 type 属性会影响 打包数据 算法 ，并决定在 抓取 Blob URL 时的 Content-Type 头。

3.3. 方法和参数

3.3.1. slice() 方法

// 通过 DOM 获取输入元素

var file = document.getElementById('file').files[0];
if(file)
{
  // 创建文件的相同副本
  // 以下两个调用是等价的

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

  // 从文件中间开始切片为一半，负数的使用

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

  // 从文件开头开始切片为一半

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

  // 从文件开头开始切片，直到距末尾 150 字节

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

3.3.2. stream() 方法

stream() 方法被调用时，必须返回调用 get stream 的结果，调用对象为 this。

3.3.3. text() 方法

text() 方法被调用时，必须运行以下步骤：

1. 调用 get stream 的结果作为 stream，调用对象为 this。

2. 调用 获取读取器 的结果作为 reader，读取自 stream。 如果抛出异常，返回一个以该异常拒绝的新 promise。

3. 将 promise 作为调用 读取所有字节 的结果，读取自 stream 并使用 reader。

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

注意： 这与 readAsText() 的行为不同， 更好地与 Fetch 的 text() 行为对齐。 具体来说，该方法将始终使用 UTF-8 编码，而 FileReader 根据 blob 的类型和传入的编码名称，可能使用不同的编码。

3.3.4. arrayBuffer() 方法

arrayBuffer() 方法被调用时，必须运行以下步骤：

1. 调用 get stream 的结果作为 stream，调用对象为 this。

2. 调用 获取读取器 的结果作为 reader，读取自 stream。 如果抛出异常，返回一个以该异常拒绝的新 promise。

3. 将 promise 作为调用 读取所有字节 的结果，读取自 stream 并使用 reader。

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

3.3.5. bytes() 方法

bytes() 方法被调用时，必须运行以下步骤：

1. 调用 get stream 的结果作为 stream，调用对象为 this。

2. 调用 获取读取器 的结果作为 reader，读取自 stream。 如果抛出异常，返回一个以该异常拒绝的新 promise。

3. 将 promise 作为调用 读取所有字节 的结果，读取自 stream 并使用 reader。

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

4. File 接口

File 对象是一个 Blob 对象，具有一个 name 属性，这个属性是一个字符串； 它可以通过构造函数在 web 应用程序中创建， 或者是对底层操作系统文件系统中的一个 字节 序列的引用。

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

注意： 这是一个对于用户代理来说实现起来非常复杂的要求， 因此它不是 必须 而是 应该 [RFC2119]。 用户代理应尽力将 File 对象的 快照状态 设置为创建引用时磁盘上存储的状态。 如果文件在引用创建之后被修改， 则该 File 的 快照状态 将与底层存储的状态不一致。 用户代理可以使用修改时间戳和其他机制来维护 快照状态， 但这留作实现细节。

当一个 File 对象引用磁盘上的文件时， 用户代理必须返回该文件的 type， 并且必须遵循以下的 文件类型指南：

• 用户代理必须将 type 以小写形式的 ASCII 编码字符串返回， 这样当它被转换为相应的字节序列时， 它是一个 可解析的 MIME 类型， 如果无法确定类型，则返回空字符串 – 0 字节。

• 当文件类型为 text/plain 时，用户代理不得在媒体类型的参数字典部分附加 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 Epoch 以来的毫秒数。 如果最后的修改日期和时间未知， 该属性必须返回当前日期和时间， 以 long long 表示自 Unix Epoch 以来的毫秒数； 这相当于 Date.now() [ECMA-262]。 如果使用构造函数创建了 File 对象， 有关此属性的更多规范条件请参见 § 4.1 构造函数。

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

var file = document.getElementById("filePicker").files[0];
var date = new Date(file.lastModified);
println("您选择的文件是 " + file.name + "，最后修改日期为 " + date.toDateString() + "。");

...

// 生成具有特定最后修改日期的文件

var d = new Date(2013, 12, 5, 16, 23, 45, 600);
var generatedFile = new File(["初稿 ...."], "Draft1.txt", {type: "text/plain", lastModified: d})

...

5. FileList 接口

注意： FileList 接口应被视为“存在风险”， 因为 Web 平台上的普遍趋势是用 Array 对象替代这种接口，正如 ECMAScript 所定义的 [ECMA-262]。 尤其是，类似 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 的 子序列化 追加到 serialized.[[Files]]。

其 反序列化步骤，给定 serialized 和 value，如下所示：

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

// uploadData 是表单元素
// fileChooser 是类型为 'file' 的输入元素
var file = document.forms['uploadData']['fileChooser'].files[0];

// 可选语法是
// var file = document.forms['uploadData']['fileChooser'].files.item(0);

if(file)
{
  // 执行文件操作
}

5.1. 属性

length, 类型为 unsigned long, 只读

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

5.2. 方法和参数

item(index)

必须返回 index 位置的 File 对象 在 FileList 中。 如果在 FileList 中没有 index 位置的 File 对象， 那么该方法必须返回 null。

index 必须被用户代理 视为表示 File 对象在 FileList 中位置的值， 其中 0 表示第一个文件。支持的属性索引 是从零到 小于 File 对象数量的数字范围。 如果没有这样的 File 对象， 那么就没有支持的属性索引。

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

6. 读取数据

6.1. 文件读取任务源

本规范定义了一个新的通用 任务源，称为 文件读取任务源， 用于本规范中排队的所有任务，这些任务用于读取与 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 对象有一个关联的 状态， 可以是 "empty"，"loading"，或者 "done"。初始状态为 "empty"。

一个 FileReader 对象有一个关联的 结果（null，一个 DOMString 或 ArrayBuffer）。 初始值为 null。

一个 FileReader 对象有一个关联的 错误（null 或 DOMException）。 初始值为 null。

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

readyState 属性的 getter 在调用时，基于 this 的 状态，并执行相应的步骤：

"empty"

返回 EMPTY

"loading"

返回 LOADING

"done"

返回 DONE

result 属性的 getter 在调用时，必须返回 this 的 结果。

error 属性的 getter 在调用时，必须返回 this 的 错误。

6.2.1. 事件处理程序内容属性

以下是事件处理程序内容属性（及其对应的事件处理程序事件类型）， 用户代理必须在作为 DOM 属性的 FileReader 上支持这些属性：

6.2.2. FileReader 状态

6.2.3. 读取文件或 Blob

FileReader 接口提供了几种 异步读取方法——readAsArrayBuffer(), readAsBinaryString(), readAsText() 和 readAsDataURL()， 用于将文件读取到内存中。

注意： 如果在同一个 FileReader 对象上调用了多个并发的读取方法， 用户代理会在 InvalidStateError 中抛出异常， 当 readyState = LOADING 时。

(FileReaderSync 提供了几种 同步读取方法。 集体来说，FileReader 和 FileReaderSync 的同步和异步读取方法被统称为 读取方法。）

6.2.3.1. readAsDataURL() 方法

readAsDataURL(blob) 方法， 被调用时，必须为 blob 启动一个 DataURL 的读取操作。

6.2.3.2. readAsText() 方法

readAsText(blob, encoding) 方法， 被调用时，必须为 blob 启动一个 Text 和 encoding 的读取操作。

6.2.3.3. readAsArrayBuffer()

readAsArrayBuffer(blob) 方法， 被调用时，必须为 blob 启动一个 ArrayBuffer 的读取操作。

6.2.3.4. readAsBinaryString() 方法

readAsBinaryString(blob) 方法， 被调用时，必须为 blob 启动一个 BinaryString 的读取操作。

注意： 推荐使用 readAsArrayBuffer() 而不是 readAsBinaryString()， 后者仅为了向后 兼容。

6.2.3.5. abort() 方法

当调用 abort() 方法时， 用户代理必须执行以下步骤：

1. 如果 this 的 状态 为 "empty" 或 this 的 状态 为 "done"，则将 this 的 result 设置为 null 并终止此算法。

2. 如果 this 的 状态 为 "loading"，则将 this 的 状态 设置为 "done" 并将 this 的 result 设置为 null。

3. 如果 任务 从 this 中存在于 文件读取任务源 的相关 任务队列 中， 则将这些 任务 从该任务队列中移除。

4. 终止 正在处理的 读取方法 的算法。

5. 触发进度事件， 事件名为 abort 在 this。

6. 如果 this 的 状态 不是 "loading"，触发进度事件，事件名为 loadend 在 this。

6.3. 打包数据

6.4. 事件

FileReader 对象必须是此规范中所有事件的事件目标。

当本规范要求 触发一个名为 e 的进度事件 时（对于某些 ProgressEvent e 在给定的 FileReader reader 上）， 以下是规范要求：

• 进度事件 e 不会冒泡。e.bubbles 必须为 false [DOM]

• 进度事件 e 不可取消。e.cancelable 必须为 false [DOM]

6.4.1. 事件概述

以下是会在 触发在 FileReader 对象上的事件。

6.4.2. 事件不变性概述

本节为说明性内容。

以下是不变性，适用于在此规范中的给定异步 读取方法 的 事件触发：

1. 一旦 loadstart 事件被触发， 对应的 loadend 会在读取完成时触发， 除非下列情况之一为真：

   • 通过调用 abort() 取消了 读取方法，并调用了新的 读取方法

   • load 事件的事件处理函数启动了新的读取

   • error 事件的事件处理函数启动了新的读取。

   注意： 事件 loadstart 和 loadend 之间不是一对一的关系。

   这个例子展示了“读取链”：在事件处理程序中启动另一个读取，而“第一个”读取继续处理。

   // 如下代码...
   reader.readAsText(file);
   reader.onload = function(){reader.readAsText(alternateFile);}
   
   .....
   
   //... loadend 事件不应为第一次读取触发
   
   reader.readAsText(file);
   reader.abort();
   reader.onabort = function(){reader.readAsText(updatedFile);}
   
   //... loadend 事件不应为第一次读取触发
   

2. 当 blob 完全读取到内存中时，将触发一个 progress 事件。

3. 在 loadstart 事件之前，不会触发 progress 事件。

4. 在 abort、load 或 error 触发后，不会触发 progress 事件。 对于给定的读取，最多只触发一次 abort、load 或 error。

5. 在 loadend 触发后，不会触发 abort、load 或 error 事件。

6.5. 在线程中读取

Web Workers 允许使用同步的 File 或 Blob 读取 API， 因为在线程上进行的读取不会阻塞主线程。 本节定义了一个可以在 Workers 内使用的同步 API [[Web Workers]]。 Workers 可以同时使用异步 API（FileReader 对象）和同步 API（FileReaderSync 对象）。

6.5.1. FileReaderSync API

此接口提供了 同步读取 File 或 Blob 对象到内存中的方法。

[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);
};

6.5.1.1. 构造函数

当调用 FileReaderSync() 构造函数时， 用户代理必须返回一个新的 FileReaderSync 对象。

6.5.1.2. readAsText()

readAsText(blob, encoding) 方法被调用时， 必须运行以下步骤：

1. 将 stream 设置为调用 get stream 方法获取的 blob 的结果。

2. 将 reader 设置为从 stream 中通过 获取 reader 方法得到的结果。

3. 将 promise 设置为通过 读取所有字节 从 stream 中 使用 reader 得到的结果。

4. 等待 promise 完成或被拒绝。

5. 如果 promise 返回的结果为 字节序列 bytes：

   1. 返回 package data 的结果，输入为 bytes，Text，blob 的 type，以及 encoding。

6. 抛出 promise 的拒绝原因。

6.5.1.3. readAsDataURL() 方法

readAsDataURL(blob) 方法， 被调用时，必须运行以下步骤：

1. 将 stream 设置为调用 get stream 方法获取的 blob 的结果。

2. 将 reader 设置为从 stream 中通过 获取 reader 方法得到的结果。

3. 将 promise 设置为通过 读取所有字节 从 stream 中使用 reader 得到的结果。

4. 等待 promise 完成或被拒绝。

5. 如果 promise 返回的结果为 字节序列 bytes：

   1. 返回 package data 的结果，输入为 bytes、DataURL 以及 blob 的 type。

6. 抛出 promise 的拒绝原因。

6.5.1.4. readAsArrayBuffer() 方法

readAsArrayBuffer(blob) 方法， 被调用时，必须运行以下步骤：

1. 将 stream 设置为调用 get stream 方法获取的 blob 的结果。

2. 将 reader 设置为从 stream 中通过 获取 reader 方法得到的结果。

3. 将 promise 设置为通过 读取所有字节 从 stream 中使用 reader 得到的结果。

4. 等待 promise 完成或被拒绝。

5. 如果 promise 返回的结果为 字节序列 bytes：

   1. 返回 package data 的结果，输入为 bytes、ArrayBuffer 以及 blob 的 type。

6. 抛出 promise 的拒绝原因。

6.5.1.5. readAsBinaryString() 方法

readAsBinaryString(blob) 方法， 被调用时，必须运行以下步骤：

1. 将 stream 设置为调用 get stream 方法获取的 blob 的结果。

2. 将 reader 设置为从 stream 中通过 获取 reader 方法得到的结果。

3. 将 promise 设置为通过 读取所有字节 从 stream 中使用 reader 得到的结果。

4. 等待 promise 完成或被拒绝。

5. 如果 promise 返回的结果为 字节序列 bytes：

   1. 返回 package data 的结果，输入为 bytes、BinaryString 以及 blob 的 type。

6. 抛出 promise 的拒绝原因。

注意： 使用 readAsArrayBuffer() 方法优先于 readAsBinaryString()， 后者是为了向后兼容而提供的。

7. 错误与异常

文件读取错误 可能会在从底层文件系统读取文件时发生。 下面列出的潜在错误情况是参考信息。

• 正在访问的 文件 或 Blob 在调用 异步读取方法 或 同步读取方法 时可能不存在。 这可能是由于在获取引用后文件已被移动或删除 （例如，与另一个应用程序并发修改）。 参见 NotFoundError。

• 某个 文件 或 Blob 可能不可读。 这可能是由于在获取对 文件 或 Blob 的引用后发生的权限问题 （例如，与另一个应用程序的并发锁定）。 此外，快照状态 可能已更改。 参见 NotReadableError。

• 用户代理可能会确定某些文件不适合在 Web 应用程序中使用。 文件在原始文件选择后可能会在磁盘上发生更改， 从而导致无效读取。 此外，某些文件和目录结构可能会被底层文件系统视为受限； 尝试从这些文件中读取可能会被视为安全违规。 参见 § 9 安全与隐私考量 以及 SecurityError。

7.1. 抛出异常或返回错误

本节为规范性内容。

在读取 文件 或 Blob 时，可能会出现错误条件。

当读取 文件 或 Blob 时，读取操作可能因错误条件而终止； 导致 get stream 算法失败的具体错误条件称为 失败原因。 失败原因 之一包括 NotFound、UnsafeFile、TooManyReads、SnapshotState 或 FileLock。

如果因某个特定 失败原因 出现错误，同步读取方法会 抛出下表中的异常。

异步读取方法使用 error 属性，返回 DOMException 对象（下表中的最合适类型）， 如果出现错误是由于某个特定 失败原因， 否则返回 null。

8. 用于 Blob 和 MediaSource 的 URL 参考

本节定义了用于引用 Blob 和 MediaSource 对象的 URL 方案。

8.1. 介绍

本节为说明性内容。

Blob（或对象）URL 是类似于 blob:http://example.com/550e8400-e29b-41d4-a716-446655440000 这样的 URL。 这使得 Blob 和 MediaSource 能够与其他仅设计用于使用 URL 的 API 进行集成，例如 img 元素。Blob URL 也可用于导航或触发本地生成数据的下载。

为此目的，URL 接口公开了两个静态方法，createObjectURL(obj) 和 revokeObjectURL(url)。 第一个方法创建从 URL 到 Blob 的映射，第二个方法撤销该映射。 只要映射存在，Blob 就不能被垃圾回收， 因此在不再需要引用时，必须注意尽快撤销 URL。 当创建 URL 的全局对象消失时，所有 URL 都会被撤销。

8.2. 模型

每个用户代理都必须维护一个 blob URL 存储。 一个 blob URL 存储 是一个 映射，其中 键 是 有效的 URL 字符串，值 是 blob URL 条目。

一个 blob URL 条目包含一个对象（类型为 Blob 或 MediaSource）和一个环境（一个环境设置对象）。

注意：规范必须使用获取 blob 对象算法来访问 blob URL 条目的对象。

键 在 blob URL 存储（也称为 blob URL）中是 有效的 URL 字符串，当 解析 后会生成一个 URL，其 方案等于 "blob"， 空主机，以及一个由一个元素组成的 路径，该元素本身也是一个 有效的 URL 字符串。

8.3. blob URL 的解析模型

对于 blob URL 的解析和获取模型的进一步要求，在 [URL] 和 [Fetch] 规范中定义。

8.3.1. blob URL 的来源

本节为说明性内容。

blob URL 的来源总是与创建该 URL 的环境相同，只要该 URL 尚未被撤销。这是通过 [URL] 规范在解析 URL 时查找 blob URL 存储 中的条目，并使用该条目返回正确的来源来实现的。

如果 URL 被撤销，来源的序列化仍将与创建 blob URL 的环境的来源序列化相同，但对于不透明的来源，来源本身可能是不同的。然而，这种区别是不可观察到的，因为已撤销的 blob URL 无法再被解析或获取。

8.3.2. blob URL 的访问限制

Blob URL 只能从存储密钥与创建 blob URL 的环境的存储密钥匹配的环境中获取。Blob URL 导航不受此限制。

8.3.3. blob URL 的生命周期

本规范通过以下步骤扩展了 卸载文档清理步骤：

1. 让 environment 为 Document 的 相关设置对象。

2. 让 store 为用户代理的 blob URL 存储。

3. 从 store 中移除所有 值 的 环境 等于 environment 的条目。

当 worker 被卸载时也需要类似的钩子。

8.4. 创建和撤销 blob URL

Blob URL 是通过 URL 对象暴露的静态方法创建和撤销的。 撤销一个 blob URL 会将 blob URL 与其引用的资源解耦，如果在撤销后对其进行解引用， 用户代理必须像发生了 网络错误 一样处理。 本节描述了 URL 规范的补充接口 [URL] 并介绍了blob URL 的创建和撤销方法。

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

myurl = window1.URL.createObjectURL(myblob);
window2.URL.revokeObjectURL(myurl);

8.4.1. Blob URL 创建和撤销的示例

Blob URL 是用于获取 Blob 对象的字符串，并且只要最初使用 URL.createObjectURL() 创建它们的 document 存在，它们就可以一直存在——请参阅§ 8.3.3 blob URL 的生命周期。

本节通过解释给出了创建和撤销 blob URL 的示例用法。

url = URL.createObjectURL(blob);
img1.src = url;
img2.src = url;

var blobURLref = URL.createObjectURL(file);
img1 = new Image();
img2 = new Image();

// 两个赋值操作均正常工作
img1.src = blobURLref;
img2.src = blobURLref;

// ... 页面加载后
// 检查两个图像是否已加载完成
if(img1.complete && img2.complete) {
  // 确保后续的引用抛出异常
  URL.revokeObjectURL(blobURLref);
} else {
  msg("无法预览图像！");
  // 撤销基于字符串的引用
  URL.revokeObjectURL(blobURLref);
}

上面的示例允许多次引用单个blob URL， 然后在两个图像对象都加载完毕后，Web 开发者撤销该blob URL字符串。 虽然不限制blob URL的使用次数提供了更大的灵活性， 但它增加了泄漏的可能性； 开发者应将其与相应的 URL.revokeObjectURL() 调用配对使用。

9. 安全和隐私考虑

本节是说明性的。

本规范允许 Web 内容读取来自底层文件系统的文件，并提供通过唯一标识符访问文件的方式，因此涉及一些安全考虑。 本规范还假设主要的用户交互是通过 HTML 表单中的 <input type="file"> 元素 [HTML]， 并且 FileReader 对象读取的所有文件均已由用户选择。 重要的安全考虑包括防止恶意的文件选择攻击（选择循环）， 防止访问系统敏感文件，并防止文件在选择后被修改。

防止选择循环

在文件选择过程中，用户可能会被与 <input type="file"> 相关联的文件选择器轰炸（陷入“必须选择”循环中，强制选择才能关闭文件选择器），用户代理可以通过使返回的 FileList 对象的大小为 0 来阻止对任何选定文件的访问。

系统敏感文件

（例如 /usr/bin 中的文件、密码文件和其他原生操作系统可执行文件）通常不应暴露给 Web 内容，并且不应通过 blob URL 进行访问。用户代理可以为同步读取方法抛出 SecurityError 异常，或为异步读取返回 SecurityError 异常。

本节是暂定的；后续草案可能会补充更多安全数据。

10. 需求和用例

本节讨论此 API 的需求，并说明一些用例。 此版本的 API 并未满足所有用例； 后续版本可能会解决这些问题。

• 一旦用户授予权限，用户代理应提供通过编程方式直接从本地文件读取和解析数据的能力。

  一个歌词查看器。 用户希望从他的 plist 文件中读取歌曲的歌词。 用户浏览选择 plist 文件。 文件被打开、读取、解析，并在 Web 应用程序中以可排序、可操作的列表形式呈现给用户。 用户可以选择歌曲以获取歌词。 用户使用“浏览文件”对话框。

• 数据应该能够存储在本地，以便以后使用，这对于 Web 应用程序的离线数据访问非常有用。

  一个日历应用程序。 用户的公司有一个日历。 用户希望将本地事件同步到公司日历，标记为“忙碌”时段（而不会泄露个人信息）。 用户浏览并选择文件。 text/calendar 文件在浏览器中解析，允许用户将文件合并为一个日历视图。 用户然后希望将文件保存回他的本地日历文件（使用“另存为”？）。 用户还可以将集成的日历文件异步发送回服务器日历存储。

• 用户代理应提供通过编程方式根据数据量和文件名保存本地文件的能力。

  注意：虽然本规范未提供触发下载的显式 API 调用，但 HTML5 规范已解决此问题。 download 属性的 a 元素会启动下载，保存具有指定名称的 File。 此 API 和 download 属性的结合 使 Web 应用程序能够创建文件并将其保存到本地。

  一个电子表格应用程序。 用户与表单交互并生成一些输入。 然后表单生成一个 CSV（逗号分隔变量）输出，供用户导入到电子表格中，并使用“保存...”。 生成的输出还可以直接集成到基于 Web 的电子表格中，并异步上传。

• 用户代理应提供一种简化的编程方式，将文件中的数据发送到远程服务器，其效率应高于当前基于表单的上传方式。

  一个视频/照片上传应用程序。 用户能够选择要上传的大文件，然后可以将其“分块传输”到服务器。

• 用户代理应提供暴露给脚本的 API，公开上述功能。 每当与文件系统进行交互时，UI 会通知用户，并且用户可以完全取消或中止事务。 用户会被通知任何文件选择，并可以取消这些选择。 无需用户干预，无法静默调用这些 API。

致谢

本规范最初由 SVG 工作组开发。特别感谢 Mark Baker 和 Anne van Kesteren 提供的反馈意见。

感谢 Robin Berjon、Jonas Sicking 和 Vsevolod Shmyroff 编辑了最初的规范。

特别感谢 Olli Pettay、Nikunj Mehta、Garrett Smith、Aaron Boodman、Michael Nordman、Jian Li、Dmitry Titov、Ian Hickson、Darin Fisher、Sam Weinig、Adrian Bateman 和 Julian Reschke。

感谢 W3C WebApps 工作组，和 public-webapps@w3.org 邮件列表上的参与者。