文件系统标准（File System Standard）

1. 引言

本节为非规范性内容。

本文件定义了文件系统 API 的基础架构。此外，还定义了一个 API，使网站可以在不先请求用户授权的情况下，访问文件系统目录。这使得网站能够在用户选择保存位置之前，将数据保存到磁盘，而无需为此类文件使用完全不同的存储机制和 API。入口为 navigator.storage.getDirectory() 方法。

2. 文件与目录

2.1. 基本概念

文件系统条目是指文件条目或目录条目。

每个文件系统条目都关联有一个查询访问算法，接收“read”或“readwrite”模式，返回一个文件系统访问结果。除非另有说明，否则该算法返回的文件系统访问结果的权限状态为“denied”，错误名称为空字符串。

每个文件系统条目还关联有一个请求访问算法，接收“read”或“readwrite”模式，返回一个文件系统访问结果。除非另有说明，否则该算法返回的文件系统访问结果的权限状态为“denied”，错误名称为空字符串。

文件系统访问结果是一个结构体，封装了查询或请求文件系统访问的结果。它有如下字段：

权限状态: 一个 PermissionState
错误名称: 一个字符串。如果权限状态为“granted”，则必须为空字符串；否则应为 DOMException 错误名称表中的名称。大多数情况下，权限状态不为“granted”时，名称应为“NotAllowedError”。

依赖本规范的规范可将此 API 视为强功能。然而，与其他强功能的权限请求算法可能抛出异常不同，文件系统条目的“查询访问”和“请求访问”算法必须在文件系统队列中并行运行，不允许抛出异常。如果算法返回的错误名称非空，调用者应通过将存储任务入队来拒绝（reject）。

注意：仅实现本规范而未实现依赖本规范的规范的实现，无需实现文件系统条目的“查询访问”和“请求访问”算法。

应考虑将访问检查算法关联到 FileSystemHandle。

每个文件系统条目有一个关联的名称（字符串）。

有效文件名指非空字符串，不等于“.”或“..”，且不包含“/”或底层平台作为路径分隔符的任何其他字符。

注意：这意味着在 Windows 上名称中不能包含“\”，但在其他操作系统可能允许。此外，底层文件系统可能对名称有进一步限制，仅为有效文件名并不保证能成功创建该文件或目录。

应考虑对文件名施加更严格的规范性限制，而不是完全交由底层文件系统决定。

文件条目还包括二进制数据（字节序列）、修改时间戳（自 Unix 纪元以来的毫秒数）、锁（仅允许为“open”“taken-exclusive”“taken-shared”之一的字符串）和共享锁数量（当前持有的共享锁数量）。

用户代理拥有一个关联的文件系统队列，即新建的并行队列。所有文件系统操作都应使用此队列。

要获取给定文件条目 file 的锁，value为“exclusive”或“shared”：

设 lock 为该文件的锁值。
设 count 为该文件的共享锁数量。
若 value 为“exclusive”：
1. 若 lock 为“open”：
  1. 将 lock 设为“taken-exclusive”。
  2. 返回“success”。
若 value 为“shared”：
1. 若 lock 为“open”：
  1. 将 lock 设为“taken-shared”。
  2. 将 count 设为 1。
  3. 返回“success”。
2. 否则，若 lock 为“taken-shared”：
  1. 将 count 加 1。
  2. 返回“success”。
返回“failure”。

注意：这些步骤必须在文件系统队列中执行。

要释放给定文件条目 file 的锁：

设 lock 为该文件的锁值。
设 count 为该文件的共享锁数量。
若 lock 为“taken-shared”：
1. 将 count 减 1。
2. 若 count 为 0，将 lock 设为“open”。
否则，将 lock 设为“open”。

注意：这些步骤必须在文件系统队列中执行。

注意：锁用于防止文件的并发修改。FileSystemWritableFileStream 需要共享锁，FileSystemSyncAccessHandle 需要独占锁。

目录条目还包含一个集合（子条目），每个子项都是文件系统条目，可以是文件条目或目录条目。

文件系统条目 entry 应至多被一个目录条目的子条目包含，该目录条目被称为 entry 的父项。若不存在这样的目录条目，则该文件系统条目的父项为 null。

注意：不同的文件系统条目可表示磁盘上的同一文件或目录，因此两者可拥有不同父项，或一者有父项而另一者无。

文件系统条目可以（但不必须）由宿主操作系统的本地文件系统上的实际文件支持，因此条目的二进制数据、修改时间戳、子条目等可能被此规范之外的应用修改。外部变化如何反映到此规范的数据结构，以及反之，留给具体实现决定。

一个文件系统条目 a 被视为与以下条目相同的条目：一个文件系统条目 b，如果 a 是 b，或者如果 a 和 b 由本地文件系统上的同一个文件或目录支持。

要解析一个文件系统定位器 child，相对于一个目录定位器 root：

令 result 为一个新的 promise。
将以下步骤入队至文件系统队列：
1. 如果 child的定位器的根不是 root的定位器的根，解决 result，值为 null，并中止这些步骤。
2. 令 childPath 为 child的定位器的路径。
3. 令 rootPath 为 root的定位器的路径。
4. 如果 childPath 被视为与以下路径相同： rootPath，解决 result，值为 « »，并中止这些步骤。
5. 如果 rootPath的大小大于 childPath的大小，解决 result，值为 null，并中止这些步骤。
6. 对于每个 index（取自 rootPath的索引）：
  1. 如果 rootPath.[[index]] 不是 childPath.[[index]]，则解决 result，值为 null，并中止这些步骤。
7. 令 relativePath 为 « »。
8. 对于每个 index（取值范围从 rootPath的大小到 rootPath的大小，不包含上界），追加 childPath.[[index]] 到 relativePath。
9. 解决 result，值为 relativePath。
返回 result。

文件系统定位器表示文件系统条目的一个可能位置。文件系统定位器可以是文件定位器或目录定位器。

每个文件系统定位器有一个关联的路径（文件系统路径），类型（FileSystemHandleKind），以及根（文件系统根）。

可考虑为每个定位器分配存储桶。

文件定位器是类型为“file”的文件系统定位器。目录定位器是类型为“directory”的文件系统定位器。

文件系统根是一个实现自定义的不透明字符串。

假设一个文件系统定位器 locator 定位到存储桶文件系统根目录下路径为 data/drafts/example.txt 的文件条目，locator 的类型为“file”，路径为 [ "data", "drafts", "example.txt" ]，根可包含例如存储桶、磁盘驱动器等相关信息。

如果文件系统定位器 a 的类型与文件系统定位器 b 的类型相同，a 的根与 b 的根相同，并且 a 的路径与 b 的路径是同一路径，则这两个定位器为同一个定位器。

定位条目算法，给定一个文件系统定位器 locator，执行如下实现自定义步骤，但需满足：

若 locator 是文件定位器，返回文件条目或 null。
若 locator 是目录定位器，返回目录条目或 null。
如果返回非 null 条目，则：
- 如果期间未执行其他文件系统操作，则用 entry 获取定位器会返回 locator。
- entry 的名称为 locator 路径的最后一个元素。

获取定位器算法，给定文件系统条目 entry，执行如下实现自定义步骤，但需满足：

若 entry 是文件条目，返回文件定位器。
若 entry 是目录条目，返回目录定位器。
若返回 locator，则在期间未执行其他文件系统操作的前提下，用 locator 定位条目会返回 entry。
entry 的名称为 locator 路径的最后一个元素。

一个文件系统路径是一个列表，包含一个或多个字符串。这可以是映射到磁盘上或内存中实际位置的虚拟路径，可以直接对应本地文件系统上的路径，也可能根本不对应磁盘上的任何文件。实际物理位置对于相应的文件系统条目而言是由实现定义的。

令 path 为以下列表 « "data", "drafts", "example.txt" »。这里并不假定磁盘上的任何位置存在名为 example.txt 的文件。

一个文件系统路径 a 被视为与以下路径相同：一个文件系统路径 b，如果 a 等于 b。

内容（属于一个文件系统定位器，包括其路径）预期不会被完整地共享给网站进程。该文件系统路径可能包含一些组成部分，网站并不知道这些部分，除非该文件系统定位器随后被解析，相对于一个父目录定位器。

2.2. `FileSystemHandle` 接口

enum FileSystemHandleKind {
  "file",
  "directory",
};

[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemHandle {
  readonly attribute FileSystemHandleKind kind;
  readonly attribute USVString name;

  Promise<boolean> isSameEntry(FileSystemHandle other);
};

FileSystemHandle 对象关联有一个定位器（即文件系统定位器）。

注意：多个 FileSystemHandle 对象可以具有相同的文件系统定位器。

当 FileSystemHandle 的定位器的路径第一个元素为空字符串时，该对象位于 bucket 文件系统中。

注意：这是一个特殊约定，仅有 bucket 文件系统的根目录路径才会包含空字符串，见 getDirectory()。路径的其它元素必须是有效文件名。

可考虑为每个定位器分配存储桶以优化此设计。

FileSystemHandle 对象是可序列化对象。

它们的序列化步骤如下，给定 value、serialized 和 forStorage：

将 serialized.[[Origin]] 设为 value 的相关设置对象的源（origin）。
将 serialized.[[Locator]] 设为 value 的定位器。

它们的反序列化步骤如下，给定 serialized 和 value：

如果 serialized.[[Origin]] 与 value 的相关设置对象的源（origin）不同源，则抛出 "DataCloneError" DOMException。
将 value 的定位器设为 serialized.[[Locator]]。

handle . kind: 如果 handle 是 FileSystemFileHandle，则返回 "file"；如果是 FileSystemDirectoryHandle，则返回 "directory"。可用于区分目录内容遍历时的文件与目录。
handle . name: 返回 handle 定位器路径的最后一个部分。

kind 的获取步骤：返回 this 的定位器的类型。

name 的获取步骤：返回 this 的定位器路径的最后一个元素（字符串）。

2.2.1.`isSameEntry()` 方法

same = await handle1 . isSameEntry(handle2): 如果 handle1 和 handle2 表示同一个文件或目录，则返回 true。

isSameEntry(other) 方法的实现步骤如下：

设 realm 为 this 的相关 Realm。
设 p 为在 realm 中新建的 promise。
将以下步骤入队至文件系统队列：
1. 如果 this 的定位器与 other 的定位器为同一个定位器，解决 p 为 true。
2. 否则，解决 p 为 false。
返回 p。

2.3. `FileSystemFileHandle` 接口

dictionary FileSystemCreateWritableOptions {
  boolean keepExistingData = false;
};

[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemFileHandle : FileSystemHandle {
  Promise<File> getFile();
  Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});
  [Exposed=DedicatedWorker]
  Promise<FileSystemSyncAccessHandle> createSyncAccessHandle();
};

注意： FileSystemFileHandle 的定位器类型为 "file"。

要创建子 FileSystemFileHandle，给定目录定位器 parentLocator 和字符串 name（在 Realm realm 中）：

创建 handle，为 realm 中新的 FileSystemFileHandle。
设 childType 为 "file"。
设 childRoot 为 parentLocator 的根的副本。
设 childPath 为 parentLocator 路径的克隆，并追加 name。
将 handle 的定位器设为：类型为 childType，根为 childRoot，路径为 childPath 的文件系统定位器。
返回 handle。

要创建新的 FileSystemFileHandle，给定文件系统根 root 和文件系统路径 path（在 Realm realm 中）：

创建 handle，为 realm 中新的 FileSystemFileHandle。
将 handle 的定位器设为：类型为 "file"，根为 root，路径为 path 的文件系统定位器。
返回 handle。

FileSystemFileHandle 对象是可序列化对象，其序列化步骤和反序列化步骤与 FileSystemHandle 相同。

2.3.1.`getFile()` 方法

file = await fileHandle . getFile(): 返回一个 File，表示 handle 的定位器所定位的文件条目在磁盘上的当前状态。如果该文件在调用后被更改或删除，返回的 File 对象可能无法再读取。

getFile() 方法的实现步骤如下：

设 result 为新的 promise。
设 locator 为 this 的定位器。
设 global 为 this 的相关全局对象。
将以下步骤入队至文件系统队列：
1. 设 entry 为用 locator 定位条目得到的结果。
2. 设 accessResult 为 entry 的“查询访问”算法结果，模式为 "read"。
3. 将一个存储任务入队（绑定 global）以执行以下步骤：
  1. 如果 accessResult 的权限状态不是 "granted"，则拒绝 result，原因为一个名称等于 accessResult 的错误名的 DOMException，并终止。
  2. 如果 entry 为 null，则以 "NotFoundError" DOMException 拒绝 result，并终止。
  3. 断言 entry 是文件条目。
  4. 创建新的 File 对象 f。
  5. 将 f 的快照状态设为 entry 当前状态。
  6. 将 f 的底层字节序列设为 entry 的二进制数据的副本。
  7. 将 f 的 name 设为 entry 的名称。
  8. 将 f 的 lastModified 设为 entry 的修改时间戳。
  9. 将 f 的 type 设为实现自定义的值（例如基于 entry 的名称或扩展名）。
    读取和快照行为仍需在 [FILE-API] 规范中更明确地定义；目前的规定仍较为粗略。
  10. 解决 result 为 f。
返回 result。

2.3.2. `createWritable()` 方法

stream = await fileHandle . createWritable()

stream = await fileHandle . createWritable({keepExistingData: true/false })

返回一个 FileSystemWritableFileStream，可用于写入文件。通过 stream 所做的更改，只有在流关闭后才会反映到 fileHandle 的定位器所定位的文件条目中。用户代理会尽量确保不会发生部分写入，即文件要么保持原内容，要么包含流关闭前写入的所有数据。

通常实现方式为先将数据写入临时文件，只有在写入流关闭时才用临时文件替换由 fileHandle 的定位器所定位的文件条目。

如果 keepExistingData 为 false 或未指定，则临时文件从空开始，否则会先复制原文件内容到临时文件。

创建 FileSystemWritableFileStream 时会对 fileHandle 的定位器所定位的文件条目获取共享锁，这会阻止在流关闭前为该条目创建 FileSystemSyncAccessHandle。

关于 createWritable 的 "inPlace" 模式（将数据写入写入器时就写入实际的底层文件，例如支持大文件或数据库的原地修改）的需求和讨论，见 WICG/file-system-access issue #67。目前 Chrome 尚未实现该功能，仍需解决如何兼顾恶意软件检查与网站对现有大文件的快速原地修改。对于 bucket 文件系统，可用 FileSystemSyncAccessHandle 接口实现原地写入。

createWritable(options) 方法实现步骤如下：

设 result 为新的 promise。
设 locator 为 this 的定位器。
设 realm 为 this 的相关 Realm。
设 global 为 this 的相关全局对象。
将以下步骤入队至文件系统队列：
1. 设 entry 为用 locator 定位条目得到的结果。
2. 设 accessResult 为 entry 的“请求访问”算法结果，模式为 "readwrite"。
3. 如果 accessResult 权限状态不是 "granted"，则将存储任务入队（global）拒绝 result，使用名称为 accessResult 的错误名称的 DOMException，并中止这些步骤。
4. 如果 entry 为 null，则将存储任务入队（global）拒绝 result，异常为 "NotFoundError" DOMException，并中止这些步骤。
5. 断言 entry 是文件条目。
6. 设 lockResult 为对 entry 获取“共享”锁的结果。
7. 将存储任务入队（global）执行：
  1. 如果 lockResult 为 "failure"，则拒绝 result，异常为 "NoModificationAllowedError" DOMException，并中止这些步骤。
  2. 创建 stream，即为 entry 创建新的 FileSystemWritableFileStream（在 realm 中）。
  3. 如果 options["keepExistingData"] 为 true，则将 stream 的 [[buffer]] 设为 entry 二进制数据的副本。
  4. 解决 result 为 stream。
返回 result。

2.3.3. `createSyncAccessHandle()` 方法

handle = await fileHandle . createSyncAccessHandle()

返回一个 FileSystemSyncAccessHandle，可用于同步读写文件。通过 handle 所做的更改可能会立即反映到 fileHandle 的定位器所定位的文件条目中。可调用 flush 方法确保更改被写入文件。

创建 FileSystemSyncAccessHandle 时会对 fileHandle 的定位器所定位的文件条目获取独占锁，在句柄关闭前，无法再为该条目创建 FileSystemSyncAccessHandle 或 FileSystemWritableFileStream。

返回的 FileSystemSyncAccessHandle 提供同步方法，适合如 WebAssembly 这类异步开销较大的场景。

目前，仅当 fileHandle 位于 bucket 文件系统时，该方法才会成功。

createSyncAccessHandle() 方法的实现步骤如下：

设 result 为新的 promise。
设 locator 为 this 的定位器。
设 realm 为 this 的相关 Realm。
设 global 为 this 的相关全局对象。
设 isInABucketFileSystem，若 this 位于 bucket 文件系统，则为 true，否则为 false。
将以下步骤入队至文件系统队列：
1. 设 entry 为用 locator 定位条目得到的结果。
2. 设 accessResult 为 entry 的“请求访问”算法结果，模式为 "readwrite"。
3. 如果 accessResult 权限状态不是 "granted"，则将存储任务入队（global）拒绝 result，使用名称为 accessResult 的错误名称的 DOMException，并中止这些步骤。
4. 如果 isInABucketFileSystem 为 false，则将存储任务入队（global）拒绝 result，异常为 "InvalidStateError" DOMException，并中止这些步骤。
5. 如果 entry 为 null，则将存储任务入队（global）拒绝 result，异常为 "NotFoundError" DOMException，并中止这些步骤。
6. 断言 entry 是文件条目。
7. 设 lockResult 为对 entry 获取“独占”锁的结果。
8. 将存储任务入队（global）执行：
  1. 如果 lockResult 为 "failure"，则拒绝 result，异常为 "NoModificationAllowedError" DOMException，并中止这些步骤。
  2. 创建 handle，即为 entry 创建新的 FileSystemSyncAccessHandle（在 realm 中）。
  3. 解决 result 为 handle。
返回 result。

2.4. `FileSystemDirectoryHandle` 接口

dictionary FileSystemGetFileOptions {
  boolean create = false;
};

dictionary FileSystemGetDirectoryOptions {
  boolean create = false;
};

dictionary FileSystemRemoveOptions {
  boolean recursive = false;
};

[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemDirectoryHandle : FileSystemHandle {
  async_iterable<USVString, FileSystemHandle>;

  Promise<FileSystemFileHandle> getFileHandle(USVString name, optional FileSystemGetFileOptions options = {});
  Promise<FileSystemDirectoryHandle> getDirectoryHandle(USVString name, optional FileSystemGetDirectoryOptions options = {});

  Promise<undefined> removeEntry(USVString name, optional FileSystemRemoveOptions options = {});

  Promise<sequence<USVString>?> resolve(FileSystemHandle possibleDescendant);
};

注意： FileSystemDirectoryHandle 的定位器类型为 "directory"。

要创建子 FileSystemDirectoryHandle，给定目录定位器 parentLocator 和字符串 name（在 Realm realm 中）：

创建 handle，为 realm 中新的 FileSystemDirectoryHandle。
设 childType 为 "directory"。
设 childRoot 为 parentLocator 的根的副本。
设 childPath 为 parentLocator 路径的克隆，并追加 name。
将 handle 的定位器设为：类型为 childType，根为 childRoot，路径为 childPath 的文件系统定位器。
返回 handle。

要创建新的 FileSystemDirectoryHandle，给定文件系统根 root 和文件系统路径 path（在 Realm realm 中）：

创建 handle，为 realm 中新的 FileSystemDirectoryHandle。
将 handle 的定位器设为：类型为 "directory"，根为 root，路径为 path 的文件系统定位器。
返回 handle。

FileSystemDirectoryHandle 对象是可序列化对象，其序列化步骤和反序列化步骤与 FileSystemHandle 相同。

2.4.1. 目录遍历

for await (let [name, handle] of directoryHandle) {}
for await (let [name, handle] of directoryHandle . entries()) {}
for await (let handle of directoryHandle . values()) {}
for await (let name of directoryHandle . keys()) {}: 遍历所有父项为 directoryHandle 的定位器所定位的目录条目的子项。遍历过程中创建或删除的条目可能会被包含或不被包含，不做保证。

未来可能会为异步可迭代器声明添加参数，例如递归遍历。

异步迭代器初始化步骤，针对 FileSystemDirectoryHandle handle 及其异步迭代器 iterator：

将 iterator 的“已访问结果”设为空集合。

要为 FileSystemDirectoryHandle handle 及其异步迭代器 iterator 获取下一个迭代结果，步骤如下：

令 promise 为新建的 promise。
将以下步骤入队到文件系统队列：
1. 令 directory 为定位条目（用 handle 的 locator）的结果。
2. 令 accessResult 为 directory 的查询访问（参数为 "read"）的结果。
3. 入队存储任务（在 handle 的相关全局对象上）以执行以下步骤：
  1. 如果 accessResult 的权限状态不是 "granted"，则拒绝 promise，错误为 accessResult 的error name 的 DOMException，终止这些步骤。
  2. 如果 directory 为 null，拒绝 promise，错误为 "NotFoundError" 的 DOMException，终止这些步骤。
    1. 断言：directory 是目录条目。
  3. 令 child 为 directory 的 children 中， iterator 的 past results 未包含其 name 的文件系统条目；如果不存在则为 null。
    
    注意：此处有意未指定遍历顺序，不同平台文件系统实现和返回顺序不同，规范不保证遍历顺序。
  4. 如果 child 为 null，则 resolve promise，值为 undefined，终止这些步骤。
  5. 追加 child 的 name 到 iterator 的 past results。
  6. 如果 child 是文件条目：
    1. 令 result 为创建子 FileSystemFileHandle 的结果，参数为 handle 的 locator 和 child 的 name，作用域为 handle 的相关 Realm。
  7. 否则：
    1. 令 result 为创建子 FileSystemDirectoryHandle 的结果，参数为 handle 的 locator 和 child 的 name，作用域为 handle 的相关 Realm。
  8. resolve promise，值为 (child 的 name, result)。
返回 promise。

2.4.2. `getFileHandle()` 方法

fileHandle = await directoryHandle . getFileHandle(name)

fileHandle = await directoryHandle . getFileHandle(name, { create: false })

返回 directoryHandle 的定位器所定位的目录条目下名为 name 的文件句柄。如果文件不存在，则 promise 拒绝。

fileHandle = await directoryHandle . getFileHandle(name, { create: true })

返回 directoryHandle 的定位器所定位的目录条目下名为 name 的文件句柄。如果文件不存在则新建文件，如果无法创建则 promise 拒绝（如同名目录已存在、文件名非法，或出于安全原因禁止创建）。

此操作需要写权限，即使目标文件已存在。如果当前句柄无写权限，可能会弹出权限请求提示。若只需只读访问且无需写权限，可调用 { create: false }。

该 getFileHandle(name, options) 方法的步骤为：

令 result 为一个新的 promise。
令 realm 为 this的相关 Realm。
令 locator 为 this的定位器。
令 global 为 this的相关全局对象。
将以下步骤入队至文件系统队列：
1. 如果 name 不是一个有效文件名，将存储任务入队，使用 global 来拒绝 result，原因为一个 TypeError 并中止这些步骤。
2. 令 entry 为以下操作的结果：定位条目，给定 locator。
3. 如果 options["create"] 为 true：
  1. 令 accessResult 为运行以下算法的结果：entry的请求访问，给定 "readwrite"。
4. 否则：
  1. 令 accessResult 为运行以下算法的结果：entry的查询访问，给定 "read"。
5. 将存储任务入队，使用 global 来运行以下步骤：
  1. 如果 accessResult的权限状态不是 "granted"，拒绝 result，原因为一个 DOMException ，其名称为 accessResult的错误名称，并中止这些步骤。
  2. 如果 entry 为 null，拒绝 result，原因为一个 "NotFoundError" DOMException 并中止这些步骤。
  3. 断言：entry 是一个目录条目。
  4. 对于每个 child（取自 entry的子条目）：
    1. 如果 child的名称等于 name：
      1. 如果 child 是一个目录条目：
        
        拒绝 result ，原因为一个 "TypeMismatchError" DOMException 并中止这些步骤。
      2. 解决 result，值为以下操作的结果：创建一个子 FileSystemFileHandle，使用 locator 和 child的名称，在 realm 中，并中止这些步骤。
  5. 如果 options["create"] 为 false：
    1. 拒绝 result，原因为一个 "NotFoundError" DOMException 并中止这些步骤。
  6. 令 child 为一个新的文件条目，其查询访问和请求访问算法就是 entry 的算法。
  7. 将 child的名称设为 name。
  8. 将 child的二进制数据设为一个空的字节序列。
  9. 将 child的修改时间戳设为当前时间。
  10. 追加 child 到 entry的子条目。
  11. 如果在底层文件系统中创建 child 时抛出异常，拒绝 result，原因为该异常，并中止这些步骤。
    
    应更明确地规定此处可能抛出哪些异常。 [议题 #11]
  12. 解决 result，值为以下操作的结果：创建一个子 FileSystemFileHandle，使用 locator 和 child的名称，在 realm 中。
返回 result。

2.4.3. `getDirectoryHandle()` 方法

subdirHandle = await directoryHandle . getDirectoryHandle(name)

subdirHandle = await directoryHandle . getDirectoryHandle(name, { create: false })

返回 directoryHandle 的定位器所定位的目录条目下名为 name 的子目录句柄。如果该目录不存在，则 promise 拒绝。

subdirHandle = await directoryHandle . getDirectoryHandle(name, { create: true })

返回 directoryHandle 的定位器所定位的目录条目下名为 name 的子目录句柄。如果该目录不存在则新建目录，若无法创建（如同名文件已存在或名称非法）则 promise 拒绝。

此操作需要写权限，即使目标目录已存在。如果当前句柄无写权限，可能会弹出权限请求提示。若仅需只读访问可调用 { create: false }。

该 getDirectoryHandle(name, options) 方法的步骤为：

令 result 为一个新的 promise。
令 realm 为 this的相关 Realm。
令 locator 为 this的定位器。
令 global 为 this的相关全局对象。
将以下步骤入队至文件系统队列：
1. 如果 name 不是一个有效文件名，将存储任务入队，使用 global 来拒绝 result，原因为一个 TypeError 并中止这些步骤。
2. 令 entry 为以下操作的结果：定位条目，给定 locator。
3. 如果 options["create"] 为 true：
  1. 令 accessResult 为运行以下算法的结果：entry的请求访问，给定 "readwrite"。
4. 否则：
  1. 令 accessResult 为运行以下算法的结果：entry的查询访问，给定 "read"。
5. 将存储任务入队，使用 global 来运行以下步骤：
  1. 如果 accessResult的权限状态不是 "granted"，拒绝 result，原因为一个 DOMException ，其名称为 accessResult的错误名称，并中止这些步骤。
  2. 如果 entry 为 null，拒绝 result，原因为一个 "NotFoundError" DOMException 并中止这些步骤。
  3. 断言：entry 是一个目录条目。
  4. 对于每个 child（取自 entry的子条目）：
    1. 如果 child的名称等于 name：
      1. 如果 child 是一个文件条目：
        
        拒绝 result ，原因为一个 "TypeMismatchError" DOMException 并中止这些步骤。
      2. 解决 result，值为以下操作的结果：创建一个子 FileSystemDirectoryHandle，使用 locator 和 child的名称，在 realm 中，并中止这些步骤。
  5. 如果 options["create"] 为 false：
    1. 拒绝 result，原因为一个 "NotFoundError" DOMException 并中止这些步骤。
  6. 令 child 为一个新的目录条目，其查询访问和请求访问算法就是 entry 的算法。
  7. 将 child的名称设为 name。
  8. 将 child的子条目设为一个空的集合。
  9. 追加 child 到 entry的子条目。
  10. 如果在底层文件系统中创建 child 时抛出异常，拒绝 result，原因为该异常，并中止这些步骤。
    
    应更明确地规定此处可能抛出哪些异常。 [议题 #11]
  11. 解决 result，值为以下操作的结果：创建一个子 FileSystemDirectoryHandle，使用 locator 和 child的名称，在 realm 中。
返回 result。

2.4.4. `removeEntry()` 方法

await directoryHandle . removeEntry(name)

await directoryHandle . removeEntry(name, { recursive: false })

如果 directoryHandle 的定位器所定位的目录条目包含名为 name 的文件，或空目录，则尝试删除该文件或目录。

删除不存在的文件或目录视为成功；尝试删除非空目录会导致 promise 拒绝。

await directoryHandle . removeEntry(name, { recursive: true })

删除 directoryHandle 的定位器所定位的目录条目下名为 name 的文件系统条目。如果该条目为目录，将递归删除其所有内容。

删除不存在的文件或目录视为成功。

该 removeEntry(name, options) 方法的步骤为：

令 result 为一个新的 promise。
令 locator 为 this的定位器。
令 global 为 this的相关全局对象。
将以下步骤入队至文件系统队列：
1. 如果 name 不是一个有效文件名，将存储任务入队，使用 global 来拒绝 result，原因为一个 TypeError 并中止这些步骤。
2. 令 entry 为以下操作的结果：定位条目，给定 locator。
3. 令 accessResult 为运行以下算法的结果：entry的请求访问，给定 "readwrite"。
4. 将存储任务入队，使用 global 来运行以下步骤：
  1. 如果 accessResult的权限状态不是 "granted"，拒绝 result，原因为一个 DOMException ，其名称为 accessResult的错误名称，并中止这些步骤。
  2. 如果 entry 为 null，拒绝 result，原因为一个 "NotFoundError" DOMException 并中止这些步骤。
  3. 断言：entry 是一个目录条目。
  4. 对于每个 child（取自 entry的子条目）：
    1. 如果 child的名称等于 name：
      1. 如果 child 是一个目录条目：
        
        如果 child的子条目不为空且 options["recursive"] 为 false：
        
        拒绝 result，原因为一个 "InvalidModificationError" DOMException 并中止这些步骤。
      2. 移除 child，从 entry的子条目中。
      3. 如果在底层文件系统中移除 child 时抛出一个异常，拒绝 result，原因为该异常，并中止这些步骤。
        
        注意：如果 recursive 为 true，移除操作可能失败且不具有原子性。某些文件或目录可能已被移除，而其他文件或目录仍然存在。
        
        应更明确地规定哪些异常可能在此抛出。 [议题 #11]
      4. 解决 result，值为 undefined。
  5. 拒绝 result，原因为一个 "NotFoundError" DOMException。
返回 result。

2.4.5. `resolve()` 方法

path = await directory . resolve(child): 如果 child 等于 directory，则 path 是空数组。; 如果 child 是 directory 的直接子项，则 path 是包含 child 名称的数组。; 如果 child 是 directory 的后代，则 path 是包含所有中间目录及 child 名称（作为最后一个元素）的数组。例如，若 directory 表示 /home/user/project，child 表示 /home/user/project/foo/bar，则返回 ['foo', 'bar']。; 否则（directory 与 child 无父子关系），path 为 null。

// 假设已获得有效目录句柄。
const dir_ref = current_project_dir;
if (!dir_ref) return;

// 获取文件句柄：
const file_ref = await dir_ref.getFileHandle(filename, { create: true });

// 检查 file_ref 是否位于 dir_ref 内：
const relative_path = await dir_ref.resolve(file_ref);
if (relative_path === null) {
    // 不在 dir_ref 内。
} else {
    // relative_path 是名称数组，表示从 dir_ref 到 file_ref 的相对路径：
    assert relative_path.pop() === file_ref.name;

    let entry = dir_ref;
    for (const name of relative_path) {
        entry = await entry.getDirectory(name);
    }
    entry = await entry.getFile(file_ref.name);

    // 此时 entry 与 file_ref 对应同一磁盘文件。
    assert await entry.isSameEntry(file_ref) === true;
}

resolve(possibleDescendant) 方法的实现步骤是：返回将 possibleDescendant 的定位器相对于 this 的定位器进行路径解析的结果。

2.5. `FileSystemWritableFileStream` 接口

enum WriteCommandType {
  "write",
  "seek",
  "truncate",
};

dictionary WriteParams {
  required WriteCommandType type;
  unsigned long long? size;
  unsigned long long? position;
  (BufferSource or Blob or USVString)? data;
};

typedef (BufferSource or Blob or USVString or WriteParams) FileSystemWriteChunkType;

[Exposed=(Window,Worker), SecureContext]
interface FileSystemWritableFileStream : WritableStream {
  Promise<undefined> write(FileSystemWriteChunkType data);
  Promise<undefined> seek(unsigned long long position);
  Promise<undefined> truncate(unsigned long long size);
};

FileSystemWritableFileStream 具有关联的 [[file]]（一个文件条目）。

FileSystemWritableFileStream 具有关联的 [[buffer]]（一个字节序列），初始为空。

注意：该缓冲区可能变得非常大，因此实现时通常不会将其全部保存在内存中，而是使用临时文件。所有对 [[buffer]] 的访问都通过返回 Promise 的方法和算法完成，因此尽管这些操作看起来是同步的，实际实现可为异步。

FileSystemWritableFileStream 具有关联的 [[seekOffset]]（一个数字），初始值为 0。

FileSystemWritableFileStream 对象是 WritableStream 对象的扩展，带有便捷方法并操作单个磁盘文件。

创建后，会有一个底层 sink 可用，流对象立即可用。所有操作都是可排队的，生产者能够响应背压。

底层 sink 的 write 方法（即 WritableStreamDefaultWriter’s write()）可接受字节类型数据或 WriteParams 作为输入。

FileSystemWritableFileStream 有一个文件位置游标，初始为文件头部偏移 0 字节。使用 write() 或通过 WritableStream 能力（即 WritableStreamDefaultWriter’s write()），该位置会根据写入的字节数推进。

同样，将 ReadableStream 管道到 FileSystemWritableFileStream 时，该位置也会根据流经的字节数更新。

getWriter() 返回 WritableStreamDefaultWriter 实例。

要创建新的 FileSystemWritableFileStream，给定文件条目 file 和 Realm realm，步骤如下：

创建 stream，为 realm 内新的 FileSystemWritableFileStream。
将 stream 的 [[file]] 设为 file。
定义 writeAlgorithm，其参数为 chunk，返回以 stream 和 chunk 运行“写入块”算法的结果。
定义 closeAlgorithm，其步骤如下：
1. 设 closeResult 为新的 promise。
2. 将以下步骤入队至文件系统队列：
  1. 设 accessResult 为 file 的“查询访问”算法结果，模式为 "readwrite"。
  2. 将一个存储任务入队（file 的相关全局对象）执行：
    1. 如果 accessResult 权限状态不是 "granted"，则拒绝 closeResult，使用以下名称的 DOMException： accessResult 的错误名称，并中止这些步骤。
    2. 执行实现自定义的恶意软件扫描和安全浏览检查。若检查失败，拒绝 closeResult，异常为 "AbortError" DOMException，并中止这些步骤。
    3. 将 stream 的 [[file]] 的二进制数据设为 stream 的 [[buffer]]。如抛异常则以该异常拒绝 closeResult 并终止。注：预期原子性更新磁盘文件内容。
    4. 将以下步骤入队至文件系统队列：
      1. 释放 stream 的 [[file]] 锁。
      2. 将存储任务入队（file 的相关全局对象），解决 closeResult 为 undefined。
3. 返回 closeResult。
定义 abortAlgorithm，其步骤如下：
1. 将此步骤入队至文件系统队列：
  1. 释放 stream 的 [[file]] 锁。
设 highWaterMark 为 1。
定义 sizeAlgorithm，返回 1。
按如下方式设置 stream： writeAlgorithm 设为 writeAlgorithm，closeAlgorithm 设为 closeAlgorithm，abortAlgorithm 设为 abortAlgorithm，highWaterMark 设为 highWaterMark，sizeAlgorithm 设为 sizeAlgorithm。
返回 stream。

写入块算法，给定一个 FileSystemWritableFileStream stream 和 chunk，执行以下步骤：

令 input 为将 chunk 转换成 FileSystemWriteChunkType 的结果。如果此步骤抛出异常，则返回一个已拒绝的 promise，原因为该异常。
令 p 为一个新的 promise。
将以下步骤入队到文件系统队列：
1. 令 accessResult 为运行 stream 的 [[file]] 的查询访问，给定 "readwrite" 的结果。
2. 将存储任务入队，以 stream 的相关全局对象运行以下步骤：
  1. 如果 accessResult 的权限状态不是 "granted"，则以一个 DOMException （其名称为 accessResult 的错误名称）拒绝 p，并中止这些步骤。
  2. 令 command 为 input["type"] （若 input 是一个字典）；否则为 "write"。
  3. 如果 command 是 "write"：
    1. 如果 input 是 undefined，或 input 是一个字典且 input["data"] 不存在，则以一个 TypeError 拒绝 p 并中止这些步骤。
    2. 令 data 为 input["data"] （若 input 是一个字典）；否则为 input。
    3. 令 writePosition 为 stream 的 [[seekOffset]]。
    4. 如果 input 是一个字典且 input["position"] 存在，则将 writePosition 设为 input["position"]。
    5. 令 oldSize 为 stream 的 [[buffer]] 的长度。
    6. 如果 data 是一个 BufferSource，令 dataBytes 为以下数据的副本： data。
    7. 否则，如果 data 是一个 Blob：
      1. 令 dataBytes 为在 data 上执行读取操作的结果。若抛出异常，则以该异常拒绝 p 并中止这些步骤。
    8. 否则：
      1. 断言：data 是一个 USVString。
      2. 令 dataBytes 为对 data 进行 UTF-8 编码的结果。
    9. 如果 writePosition 大于 oldSize，则在 stream 的 [[buffer]] 末尾追加 writePosition - oldSize 个 0x00 (NUL) 字节。
      
      注意：期望实现表现为被跳过的文件内容确实用 NUL 字节填充。这并不意味着这些字节必须真的写入磁盘并占用空间。多数文件系统支持所谓稀疏文件，即这些 NUL 字节不占用实际磁盘空间。
    10. 令 head 为一个包含 stream 的 [[buffer]] 前 writePosition 个字节的字节序列。
    11. 令 tail 为空的字节序列。
    12. 如果 writePosition + data 的长度小于 oldSize：
      1. 令 tail 为一个字节序列，包含 stream 的 [[buffer]] 最后 oldSize - (writePosition + data 的长度) 个字节。
    13. 将 stream 的 [[buffer]] 设为 head、data 与 tail 的连接。
    14. 如果前面修改 stream 的 [[buffer]] 的操作因超出存储配额而失败，则以一个 QuotaExceededError 拒绝 p 并中止这些步骤，且保持 stream 的 [[buffer]] 不变。
      
      注意：存储配额仅适用于存储在存储桶文件系统中的文件。但此操作仍可能在其他文件上失败，例如目标磁盘空间不足。
    15. 将 stream 的 [[seekOffset]] 设为 writePosition + data 的长度。
    16. 解决 p。
  4. 否则，如果 command 是 "seek"：
    1. 断言：chunk 是一个字典。
    2. 如果 chunk["position"] 不存在，则以一个 TypeError 拒绝 p 并中止这些步骤。
    3. 将 stream 的 [[seekOffset]] 设为 chunk["position"]。
    4. 解决 p。
  5. 否则，如果 command 是 "truncate"：
    1. 断言：chunk 是一个字典。
    2. 如果 chunk["size"] 不存在，则以一个 TypeError 拒绝 p 并中止这些步骤。
    3. 令 newSize 为 chunk["size"]。
    4. 令 oldSize 为 stream 的 [[buffer]] 的长度。
    5. 如果 newSize 大于 oldSize：
      1. 将 stream 的 [[buffer]] 设为一个字节序列，由 stream 的 [[buffer]] 与包含 newSize-oldSize 个 0x00 字节的字节序列拼接而成。
      2. 如果前一步操作因超出存储配额而失败，则以一个 QuotaExceededError 拒绝 p 并中止这些步骤，且保持 stream 的 [[buffer]] 不变。
        
        注意：存储配额仅适用于存储在存储桶文件系统中的文件。但此操作仍可能在其他文件上失败，例如目标磁盘空间不足。
    6. 否则，如果 newSize 小于 oldSize：
      1. 将 stream 的 [[buffer]] 设为一个字节序列，包含 stream 的 [[buffer]] 中前 newSize 个字节。
    7. 如果 stream 的 [[seekOffset]] 大于 newSize，则将 stream 的 [[seekOffset]] 设为 newSize。
    8. 解决 p。
返回 p。

2.5.1. `write()` 方法

await stream . write(data)

await stream . write({ type: "write", data: data })

将 data 的内容写入与 stream 关联的文件（从当前文件游标偏移处）。

只有在关闭流后，变更才会真正写入磁盘文件。更改通常会先写入临时文件。

await stream . write({ type: "write", position: position, data: data })

将 data 的内容写入与 stream 关联的文件（从文件头部 position 字节处），并将文件游标更新至写入末尾位置。

只有在关闭流后，变更才会真正写入磁盘文件。更改通常会先写入临时文件。

await stream . write({ type: "seek", position: position })

将文件游标偏移更新为距文件头部 position 字节处。

await stream . write({ type: "truncate", size: size })

将与 stream 关联的文件尺寸调整为 size 字节。如果 size 大于当前文件大小，则用 null 字节补齐，否则截断文件。

当调用 truncate 时，文件游标也会被更新：若游标小于 size，保持不变；若大于 size，则设为 size。这样保证后续写入不会出错。

只有在关闭流后，变更才会真正写入磁盘文件。更改通常会先写入临时文件。

write(data) 方法的实现步骤如下：

设 writer 为针对 this 获取写入器的结果。
设 result 为向 writer 写入块 data 的结果。
释放 writer。
返回 result。

2.5.2. `seek()` 方法

await stream . seek(position): 将文件游标偏移更新为距文件头部 position 字节处。

seek(position) 方法的实现步骤如下：

设 writer 为针对 this 获取写入器的结果。
设 result 为向 writer 写入块 «[ "type" → "seek", "position" → position ]» 的结果。
释放 writer。
返回 result。

2.5.3. `truncate()` 方法

await stream . truncate(size)

将与 stream 关联的文件尺寸调整为 size 字节。如果 size 大于当前文件大小，则用 null 字节补齐，否则截断文件。

当调用 truncate 时，文件游标也会被更新：若游标小于 size，保持不变；若大于 size，则设为 size。这样保证后续写入不会出错。

只有在关闭流后，变更才会真正写入磁盘文件。更改通常会先写入临时文件。

truncate(size) 方法的实现步骤如下：

设 writer 为针对 this 获取写入器的结果。
设 result 为向 writer 写入块 «[ "type" → "truncate", "size" → size ]» 的结果。
释放 writer。
返回 result。

2.6. `FileSystemSyncAccessHandle` 接口

dictionary FileSystemReadWriteOptions {
  [EnforceRange] unsigned long long at;
};

[Exposed=DedicatedWorker, SecureContext]
interface FileSystemSyncAccessHandle {
  unsigned long long read(AllowSharedBufferSource buffer,
                          optional FileSystemReadWriteOptions options = {});
  unsigned long long write(AllowSharedBufferSource buffer,
                           optional FileSystemReadWriteOptions options = {});

  undefined truncate([EnforceRange] unsigned long long newSize);
  unsigned long long getSize();
  undefined flush();
  undefined close();
};

FileSystemSyncAccessHandle 具有关联的 [[file]]（一个文件条目）。

FileSystemSyncAccessHandle 具有关联的 [[state]]，一个字符串，只能为 "open" 或 "closed"。

FileSystemSyncAccessHandle 是能够对单个文件进行读写、获取和更改其大小的对象。

FileSystemSyncAccessHandle 提供同步方法。这在异步操作开销较大的场景（例如 WebAssembly）中带来更高性能。

FileSystemSyncAccessHandle 有一个文件位置游标，初始为文件头部偏移 0 字节。

要创建新的 FileSystemSyncAccessHandle，给定文件条目 file 和 Realm realm，步骤如下：

创建 handle，为 realm 内新的 FileSystemSyncAccessHandle。
将 handle 的 [[file]] 设为 file。
将 handle 的 [[state]] 设为 "open"。
返回 handle。

2.6.1. `read()` 方法

handle . read(buffer)
handle . read(buffer, { at }): 将与 handle 关联的文件内容读取到 buffer，可选地从指定偏移处读取。; 调用 read() 时，文件游标会更新为最后读取字节的下一个字节。

指定当从一个已被外部修改的文件读取时 Access Handles 应当如何响应。 [Issue #35]

read(buffer, FileSystemReadWriteOptions:
                options)

方法的步骤如下：

如果 this 的 [[state]] 为 "closed"， throw 一个 "InvalidStateError" DOMException。
令 bufferSize 为 buffer 的 byte length。
令 fileContents 为 this 的 [[file]] 的 binary data。
令 fileSize 为 fileContents 的 length。
令 readStart 为 options["at"] （如果 options["at"] exists）；否则为 this 的 file position cursor。
如果底层文件系统不支持从偏移 readStart 读取， throw 一个 TypeError。
如果 readStart 大于 fileSize：
1. 将 this 的 file position cursor 设为 fileSize。
2. 返回 0。
令 readEnd 为 readStart + (bufferSize − 1)。
如果 readEnd 大于 fileSize，则将 readEnd 设为 fileSize。
令 bytes 为一个 byte sequence，包含 fileContents 中从 readStart 到 readEnd 的字节。
令 result 为 bytes 的 length。
如果前面从 fileContents 读取的操作失败：
1. 如果发生部分读取且读入 bytes 的字节数已知，将 result 设为已读取的字节数。
2. 否则将 result 设为 0。
令 arrayBuffer 为 buffer 的 underlying buffer。
Write bytes 到 arrayBuffer 中。
将 this 的 file position cursor 设为 readStart + result。
返回 result。

2.6.2. `write()` 方法

handle . write(buffer)
handle . write(buffer, { at }): 将 buffer 的内容写入与 handle 关联的文件，可选地从指定偏移处写入，并返回写入的字节数。检查返回的字节数可用于检测和处理错误或部分写入。; 调用 write 时，文件游标会更新为最后写入字节的下一个字节。

write(buffer, FileSystemReadWriteOptions:
                options)

方法的步骤如下：

如果 this 的 [[state]] 为 "closed"，抛出一个 "InvalidStateError" DOMException。
令 writePosition 为 options["at"] （如果 options["at"] 存在）；否则为 this 的文件位置游标。
如果底层文件系统不支持写入到偏移 writePosition，抛出一个 TypeError。
令 fileContents 为 this 的 [[file]] 的二进制数据的一个副本。
令 oldSize 为 fileContents 的长度。
令 bufferSize 为 buffer 的字节长度。
如果 writePosition 大于 oldSize，则在 fileContents 末尾追加 writePosition − oldSize 个 0x00 (NUL) 字节。

注意：期望实现表现为被跳过的文件内容确实用 NUL 字节填充。这并不意味着这些字节必须真的写入磁盘并占用空间。多数文件系统支持所谓稀疏文件（sparse files），这些 NUL 字节不占用实际磁盘空间。
令 head 为一个字节序列，包含 fileContents 的前 writePosition 个字节。
令 tail 为空的字节序列。
如果 writePosition + bufferSize 小于 oldSize：
1. 将 tail 设为一个字节序列，包含 fileContents 最后 oldSize − (writePosition + bufferSize) 个字节。
令 newSize 为 head 的长度 + bufferSize + tail 的长度。
如果 newSize − oldSize 超出可用存储配额，抛出一个 QuotaExceededError。
将 this 的 [[file]] 的二进制数据设为 head、buffer 的内容与 tail 的连接。

注意：用于访问 buffer 内容的机制被刻意保持模糊。实现很可能为了性能而直接对宿主操作系统发出写调用（而不是创建 buffer 的副本），这使得无法详细规定写入顺序及部分写入的结果。
如果前面修改 this 的 [[file]] 的二进制数据的操作失败：
1. 如果发生部分写入且从 buffer 写入的字节数已知：
  1. 令 bytesWritten 为从 buffer 写入的字节数。
  2. 将 this 的文件位置游标设为 writePosition + bytesWritten。
  3. 返回 bytesWritten。
2. 否则抛出一个 "InvalidStateError" DOMException。
将 this 的文件位置游标设为 writePosition + bufferSize。
返回 bufferSize。

2.6.3. `truncate()` 方法

handle . truncate(newSize): 将与 handle 关联的文件长度调整为 newSize 字节。如果 newSize 大于当前文件大小，则用 null 字节填充，否则截断文件。; 调用 truncate 时，如果游标小于 newSize 保持不变，否则大于 newSize 时设为 newSize。

该 truncate(newSize) 方法的步骤为：

如果 this 的 [[state]] 为 "closed"，抛出一个 "InvalidStateError" DOMException。
令 fileContents 为 this 的 [[file]] 的二进制数据的一份副本。
令 oldSize 为长度（即 this 的 [[file]] 的二进制数据的长度）。
如果底层文件系统不支持将文件大小设为 newSize，则抛出一个 TypeError。
如果 newSize 大于 oldSize：
1. 如果 newSize − oldSize 超过了可用的存储配额，抛出一个 QuotaExceededError。
2. 将 this 的 [[file]] 设为一个字节序列，该字节序列由 fileContents 与一个包含 newSize − oldSize 个 0x00 字节的字节序列连接而成。
3. 如果前述步骤中修改 this 的 [[file]] 的二进制数据的操作失败，抛出一个 "InvalidStateError" DOMException。
否则，如果 newSize 小于 oldSize：
1. 将 this 的 [[file]] 设为一个字节序列，该序列包含 fileContents 中前 newSize 个字节。
2. 如果前述步骤中修改 this 的 [[file]] 的二进制数据的操作失败，抛出一个 "InvalidStateError" DOMException。
如果 this 的文件位置游标大于 newSize，则将文件位置游标设为 newSize。

2.6.4. `getSize()` 方法

handle . getSize(): 返回与 handle 关联的文件的大小（字节数）。

getSize() 方法的步骤为：

如果 this 的 [[state]] 为 "closed"，抛出一个 "InvalidStateError" DOMException。
返回 this 的 [[file]] 的二进制数据的长度。

2.6.5. `flush()` 方法

handle . flush(): 确保与 handle 关联的文件内容包含通过 write() 所做的所有修改。

flush() 方法的步骤为：

如果 this 的 [[state]] 为 "closed"，抛出一个 "InvalidStateError" DOMException。
尝试将该文件内容的所有已缓存修改传输到底层文件系统的存储设备。

注意：这也被称为刷新 (flushing)。在某些文件系统（例如内存文件系统）上可能是空操作，因为它们没有可刷新到的“磁盘”。

2.6.6. `close()` 方法

handle . close(): 关闭该访问句柄；若已关闭则无操作。之后无法再对其进行任何操作，并且会释放与 handle 关联的 [[file]] 的锁。

close() 方法的实现步骤如下：

如果 this 的 [[state]] 为 "closed"，直接返回。
将 this 的 [[state]] 设为 "closed"。
设 lockReleased 为 false。
设 file 为 this 的 [[file]]。
将以下步骤入队至文件系统队列：
1. 释放 file 的锁。
2. 将 lockReleased 设为 true。
暂停，直到 lockReleased 为 true。

注意：该方法不保证所有文件修改会立即写入底层存储。如需此保证，应先调用 flush()。

3. 访问 Bucket 文件系统

bucket 文件系统是一种存储端点，其标识符为 "fileSystem"，类型为 « "local" »，配额为 null。

存储端点应在 [storage] 标准中定义，而不是在此处定义。应将其合并到那里的表格中。

注意：虽然用户代理通常会通过将 bucket 文件系统的内容持久化到磁盘来实现，但并不意味着用户可以轻易访问其内容。同样，也不要求磁盘上实际存在与 bucket 文件系统子项同名的文件或目录。

[SecureContext]
partial interface StorageManager {
  Promise<FileSystemDirectoryHandle> getDirectory();
};

directoryHandle = await navigator . storage . getDirectory(): 返回 bucket 文件系统的根目录。

getDirectory() 方法的实现步骤如下：

令 environment 为当前设置对象。
令 map 为以 environment 和 "fileSystem" 运行获取本地存储 bottle 映射的结果。如果返回失败，则返回带拒绝的 promise，错误为 "SecurityError" 的 DOMException。
如果 map["root"] 不存在：
1. 令 dir 为新建的目录条目，其查询访问和请求访问算法始终返回文件系统访问结果，其权限状态为 "granted"，error name 为空字符串。
2. 将 dir 的 name 设为空字符串。
3. 将 dir 的 children 设为空有序集合。
4. 将 map["root"] 设为 dir。
令 root 为实现自定义的不透明字符串。
令 path 为 « 空字符串 »。
令 handle 为创建新的 FileSystemDirectoryHandle，参数为 root 和 path，作用域为当前 Realm 的结果。

注意： root 可能包含如存储桶等相关标识信息。
断言：以 handle 的 locator 执行定位条目，返回的目录条目与 map["root"]相同。
返回带解析的 promise，值为 handle。

致谢

特别感谢 Alex Danilo, Anne van Kesteren, Anoesj Sadraee, Austin Sullivan, Chase Phillips, Daseul Lee, Dru Knox, Edgar Chen, Emanuel Krivoy, Hazim Mohamed, Ingvar Stepanyan, Jari Jalkanen, Joshua Bell, Kagami Sascha Rosylight, Marcos Cáceres, Martin Thomson, Olivier Yiptong, Philip Jägenstedt, Randell Jesup, Richard Stotz, Ruth John, Sid Vishnoi, Sihui Liu, Stefan Sauer, Thomas Steiner, Victor Costan，以及 Youenn Fablet 的大力支持！

本标准由 Marijn Kruisselbrink（Google，mek@chromium.org）编写。

知识产权声明

本 Living Standard 包含来自 W3C WICG 的 File System Access 的内容，依据 W3C 软件和文档许可提供。

本规范为 Living Standard。如需专利审查版本，请参见 Living Standard Review Draft。

文件系统（File System）

摘要（Abstract）

1. 引言

2. 文件与目录

2.1. 基本概念

2.2. `FileSystemHandle` 接口

2.2.1.`isSameEntry()` 方法

2.3. `FileSystemFileHandle` 接口

2.3.1.`getFile()` 方法

2.3.2. `createWritable()` 方法

2.3.3. `createSyncAccessHandle()` 方法

2.4. `FileSystemDirectoryHandle` 接口

2.4.1. 目录遍历

2.4.2. `getFileHandle()` 方法

2.4.3. `getDirectoryHandle()` 方法

2.4.4. `removeEntry()` 方法

2.4.5. `resolve()` 方法

2.5. `FileSystemWritableFileStream` 接口

2.5.1. `write()` 方法

2.5.2. `seek()` 方法

2.5.3. `truncate()` 方法

2.6. `FileSystemSyncAccessHandle` 接口

2.6.1. `read()` 方法

2.6.2. `write()` 方法

2.6.3. `truncate()` 方法

2.6.4. `getSize()` 方法

2.6.5. `flush()` 方法

2.6.6. `close()` 方法

3. 访问 Bucket 文件系统

致谢

知识产权声明

索引

本规范定义的术语

引用中定义的术语

参考文献

规范性引用

IDL 索引

文件系统（File System）

摘要（Abstract）

1. 引言

2. 文件与目录

2.1. 基本概念

2.2. FileSystemHandle 接口

2.2.1.isSameEntry() 方法

2.3. FileSystemFileHandle 接口

2.3.1.getFile() 方法

2.3.2. createWritable() 方法

2.3.3. createSyncAccessHandle() 方法

2.4. FileSystemDirectoryHandle 接口

2.4.1. 目录遍历

2.4.2. getFileHandle() 方法

2.4.3. getDirectoryHandle() 方法

2.4.4. removeEntry() 方法

2.4.5. resolve() 方法

2.5. FileSystemWritableFileStream 接口

2.5.1. write() 方法

2.5.2. seek() 方法

2.5.3. truncate() 方法

2.6. FileSystemSyncAccessHandle 接口

2.6.1. read() 方法

2.6.2. write() 方法

2.6.3. truncate() 方法

2.6.4. getSize() 方法

2.6.5. flush() 方法

2.6.6. close() 方法

3. 访问 Bucket 文件系统

致谢

知识产权声明

索引

本规范定义的术语

引用中定义的术语

参考文献

规范性引用

IDL 索引

2.2. `FileSystemHandle` 接口

2.2.1.`isSameEntry()` 方法

2.3. `FileSystemFileHandle` 接口

2.3.1.`getFile()` 方法

2.3.2. `createWritable()` 方法

2.3.3. `createSyncAccessHandle()` 方法

2.4. `FileSystemDirectoryHandle` 接口

2.4.2. `getFileHandle()` 方法

2.4.3. `getDirectoryHandle()` 方法

2.4.4. `removeEntry()` 方法

2.4.5. `resolve()` 方法

2.5. `FileSystemWritableFileStream` 接口

2.5.1. `write()` 方法

2.5.2. `seek()` 方法

2.5.3. `truncate()` 方法

2.6. `FileSystemSyncAccessHandle` 接口

2.6.1. `read()` 方法

2.6.2. `write()` 方法

2.6.3. `truncate()` 方法

2.6.4. `getSize()` 方法

2.6.5. `flush()` 方法

2.6.6. `close()` 方法