[zh-cn]: initial the translation of FileSystemWritableFileStream

files/zh-cn/web/api/filesystemwritablefilestream/index.md

@@ -0,0 +1,76 @@
+---
+title: FileSystemWritableFileStream
+slug: Web/API/FileSystemWritableFileStream
+---
+
+{{securecontext_header}}{{APIRef("File System API")}}
+
+{{domxref("File System API", "文件系统 API", "", "nocode")}} 的 **`FileSystemWritableFileStream`** 接口是一类附加了便于操作磁盘上单个文件的方法的 {{domxref('WritableStream')}} 对象。这个接口通过 {{domxref('FileSystemFileHandle.createWritable()')}} 方法来访问。
+
+{{InheritanceDiagram}}
+
+## 实例属性
+
+_继承父接口 {{DOMxRef("WritableStream")}} 的属性。_
+
+## 实例方法
+
+_继承父接口 {{DOMxRef("WritableStream")}} 的方法。_
+
+- {{domxref('FileSystemWritableFileStream.write()')}}
+  - : 向调用此方法的文件写入内容，写入到文件当前指针偏移处。
+- {{domxref('FileSystemWritableFileStream.seek()')}}
+  - : 更新文件当前指针偏移到指定位置（以字节为单位）。
+- {{domxref('FileSystemWritableFileStream.truncate()')}}
+  - : 将与流相关联的文件调整为指定的字节大小。
+
+## 示例
+
+下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 {{domxref('FileSystemFileHandle')}}。由此，使用 {{domxref('FileSystemFileHandle.createWritable()')}} 方法创建一个写入流。
+
+然后向流中写入一个文本字符串，随后关闭该流。
+
+```js
+async function saveFile() {
+  // 创建一个新句柄。
+  const newHandle = await window.showSaveFilePicker();
+
+  // 创建一个 FileSystemWritableFileStream 用于写入。
+  const writableStream = await newHandle.createWritable();
+
+  // 写入我们的文件。
+  await writableStream.write("This is my file content");
+
+  // 关闭文件并将内容写入磁盘。
+  await writableStream.close();
+}
+```
+
+下面的例子展示能够向 `write()` 方法传递的不同选项。
+
+```js
+// 只传递数据（没有选项）
+writableStream.write(data);
+
+// 向流中指定位置写入数据
+writableStream.write({ type: "write", position, data });
+
+// 将文件当前的指针更新到指定的偏移位置
+writableStream.write({ type: "seek", position });
+
+// 调整文件至指定字节长度
+writableStream.write({ type: "truncate", size });
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- [文件系统 API](/zh-CN/docs/Web/API/File_System_API)
+- [文件系统访问 API：简化本地文件访问](https://developer.chrome.com/articles/file-system-access/)

files/zh-cn/web/api/filesystemwritablefilestream/seek/index.md

@@ -0,0 +1,79 @@
+---
+title: FileSystemWritableFileStream：seek() 方法
+slug: Web/API/FileSystemWritableFileStream/seek
+---
+
+{{securecontext_header}}{{APIRef("File System API")}}
+
+{{domxref("FileSystemWritableFileStream")}} 接口的 **`seek()`** 方法用于更新文件当前指针的偏移到指定的位置（以字节为单位）。
+
+## 语法
+
+```js-nolint
+seek(position)
+```
+
+### 参数
+
+- `position`
+  - : 一个数字，表示从文件开头起的字节位置。
+
+### 返回值
+
+一个 {{jsxref('Promise')}}，会兑现 `undefined`。
+
+### 异常
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : 如果 {{domxref('PermissionStatus.state')}} 不为 `granted`，抛出此异常。
+- {{jsxref("TypeError")}}
+  - : 如果 `position` 参数不是一个数字或者未定义，抛出此错误。
+
+## 示例
+
+下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 {{domxref('FileSystemFileHandle')}}。由此，使用 {{domxref('FileSystemFileHandle.createWritable()')}} 方法创建一个写入流。
+
+然后我们按以下流程写入内容到流中：
+
+1. 向流中写入一个字符串。
+2. 使用 `seek()` 方法将指针放置到流的开头。
+3. 向流中写入第二个字符串，覆写第一次写入的。
+
+随后将流关闭。
+
+```js
+async function saveFile() {
+  try {
+    // 创建一个新句柄。
+    const newHandle = await window.showSaveFilePicker();
+
+    // 创建一个 FileSystemWritableFileStream 用于写入。
+    const writableStream = await newHandle.createWritable();
+
+    // 写入我们的文件。
+    await writableStream.write("My first file content");
+    await writableStream.seek(0);
+    await writableStream.write("My second file content");
+
+    // 关闭文件并将内容写入磁盘。
+    await writableStream.close();
+  } catch (err) {
+    console.error(err.name, err.message);
+  }
+}
+```
+
+如果你运行了上面的函数，然后打开磁盘上被创建的文件，你应该会看到文本“My second file content”。
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- [文件系统 API](/zh-CN/docs/Web/API/File_System_API)
+- [文件系统访问 API：简化本地文件访问](https://developer.chrome.com/articles/file-system-access/)

files/zh-cn/web/api/filesystemwritablefilestream/truncate/index.md

@@ -0,0 +1,87 @@
+---
+title: FileSystemWritableFileStream：truncate() 方法
+slug: Web/API/FileSystemWritableFileStream/truncate
+---
+
+{{securecontext_header}}{{APIRef("File System API")}}
+
+{{domxref("FileSystemWritableFileStream")}} 接口的 **`truncate()`** 方法用于将与流相关联的文件调整为指定字节大小。
+
+如果指定的大小大于文件当前的大小，文件会被用 `0x00` 字节补充。
+
+调用 `truncate()` 方法同时也会更新文件的指针。如果偏移小于大小，指针会保留原位。如果偏移大于大小，偏移会被设为相应的大小。这是为了确保随后的写入操作不会发生错误。
+
+在流被关闭前，更改不会写入到磁盘上实际的文件，而是通常会被先写入到临时文件。
+
+## 语法
+
+```js-nolint
+truncate(size)
+```
+
+### 参数
+
+- `size`
+  - : 一个数字，表示要将流调整到的字节数。
+
+### 返回值
+
+一个 {{jsxref('Promise')}}，会兑现 `undefined`。
+
+### 异常
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : 如果 {{domxref('PermissionStatus.state')}} 不为 `granted`，抛出此异常。
+- `QuotaExceededError` {{domxref("DOMException")}}
+  - : 如果文件新的大小大于文件原来的大小并且超出了浏览器的[存储配额](/zh-CN/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria)，抛出此异常。
+- {{jsxref("TypeError")}}
+  - : 如果 `size` 参数不是一个数字或者未定义，抛出此错误。
+
+## 示例
+
+下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 {{domxref('FileSystemFileHandle')}}。由此，使用 {{domxref('FileSystemFileHandle.createWritable()')}} 方法创建一个写入流。
+
+然后我们按以下流程写入内容到流中：
+
+1. 向流中写入一个字符串。
+2. 使用 `truncate()` 方法将文件大小调整为 8 字节。
+3. 向流中写入第二个字符串，覆写第一次写入的。
+
+随后将流关闭。
+
+```js
+async function saveFile() {
+  try {
+    // 创建一个新句柄。
+    const newHandle = await window.showSaveFilePicker();
+
+    // 创建一个 FileSystemWritableFileStream 用于写入。
+    const writableStream = await newHandle.createWritable();
+
+    // 写入我们的文件。
+    await writableStream.write("This is my first file content");
+    await writableStream.truncate(8);
+    await writableStream.write("my second file content");
+
+    // 关闭文件并将内容写入磁盘。
+    await writableStream.close();
+  } catch (err) {
+    console.error(err.name, err.message);
+  }
+}
+```
+
+如果你运行了上面的函数，然后打开磁盘上被创建的文件，你应该会看到文本“This is my second file content”。
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- [文件系统 API](/zh-CN/docs/Web/API/File_System_API)
+- [文件系统访问 API：简化本地文件访问](https://developer.chrome.com/articles/file-system-access/)

files/zh-cn/web/api/filesystemwritablefilestream/write/index.md

@@ -0,0 +1,102 @@
+---
+title: FileSystemWritableFileStream：write() 方法
+slug: Web/API/FileSystemWritableFileStream/write
+---
+
+{{securecontext_header}}{{APIRef("File System API")}}
+
+{{domxref("FileSystemWritableFileStream")}} 接口的 **`write()`** 方法用于在调用此方法的文件上的当前指针偏移处写入内容。
+
+在流被关闭前，更改不会写入到磁盘上实际的文件，而是通常会被先写入到临时文件。这个方法也能被用于定位到流中的字节点位还有进行裁剪以改变文件内容的总字节数。
+
+## 语法
+
+```js-nolint
+write(data)
+```
+
+### 参数
+
+- `data`
+
+  - : 可以是以下之一：
+
+    - 用于写入的文件数据，可以是 {{jsxref("ArrayBuffer")}}、{{jsxref("TypedArray")}}、{{jsxref("DataView")}}、{{domxref('Blob')}} 或字符串形式。
+    - 一个包含以下属性的对象：
+
+      - `type`
+        - : 一个字符串，值为 `"write"`、`"seek"` 或 `"truncate"`。
+      - `data`
+        - : 用于写入的文件数据，可以是 {{jsxref("ArrayBuffer")}}、{{jsxref("TypedArray")}}、{{jsxref("DataView")}}、{{domxref('Blob')}} 或字符串形式。这个属性要求 `type` 被设为 `"write"`。
+      - `position`
+        - : 当 `type` 为 `"seek"` 时，表示文件当前指针应该移动到的位置。`type` 被设为 `"write"` 时也可以使用，这种情况下将会在指定的位置开始写入。
+      - `size`
+        - : 一个数字，表示流应当包含的字节数。这个属性要求 `type` 被设为 `"truncate"`。
+
+### 返回值
+
+一个 {{jsxref('Promise')}}，会兑现 `undefined`。
+
+### 异常
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : 如果 {{domxref('PermissionStatus.state')}} 不为 `granted`，抛出此异常。
+- `QuotaExceededError` {{domxref("DOMException")}}
+  - : 如果文件新的大小大于文件原来的大小并且超出了浏览器的[存储配额](/zh-CN/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria)，抛出此异常。
+- {{jsxref("TypeError")}}
+  - : 如果未定义 `data` 或者 `position` 或 `size` 选项的值无效，抛出此错误。
+
+## 示例
+
+下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 {{domxref('FileSystemFileHandle')}}。由此，使用 {{domxref('FileSystemFileHandle.createWritable()')}} 方法创建一个写入流。
+
+然后向流中写入一个文本字符串，随后关闭该流。
+
+```js
+async function saveFile() {
+  try {
+    // 创建一个新句柄。
+    const newHandle = await window.showSaveFilePicker();
+
+    // 创建一个 FileSystemWritableFileStream 用于写入。
+    const writableStream = await newHandle.createWritable();
+
+    // 写入我们的文件。
+    await writableStream.write("This is my file content");
+
+    // 关闭文件并将内容写入磁盘。
+    await writableStream.close();
+  } catch (err) {
+    console.error(err.name, err.message);
+  }
+}
+```
+
+下面的例子展示能够向 `write()` 方法传递的不同选项。
+
+```js
+// 只传递数据（没有选项）
+writableStream.write(data);
+
+// 向流中指定位置写入数据
+writableStream.write({ type: "write", position, data });
+
+// 将文件当前的指针更新到指定的偏移位置
+writableStream.write({ type: "seek", position });
+
+// 调整文件至指定字节长度
+writableStream.write({ type: "truncate", size });
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- [文件系统 API](/zh-CN/docs/Web/API/File_System_API)
+- [文件系统访问 API：简化本地文件访问](https://developer.chrome.com/articles/file-system-access/)