From d7e2acc40e6271211bc175103047576029489af9 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Sat, 25 Nov 2023 21:47:19 +0800 Subject: [PATCH 1/4] [zh-cn]: add the translation of ArrayBuffer.transfer() --- .../arraybuffer/transfer/index.md | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md diff --git a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md new file mode 100644 index 00000000000000..d21a790b7998f3 --- /dev/null +++ b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md @@ -0,0 +1,121 @@ +--- +title: ArrayBuffer.prototype.transfer() +slug: Web/JavaScript/Reference/Global_Objects/ArrayBuffer/transfer +l10n: + sourceCommit: fb236a32b20d1985b35b1c0c25ce99f2a0e0d5fe +--- + +{{JSRef}} {{SeeCompatTable}} + +{{jsxref("ArrayBuffer")}} 实例的 **`transfer()`** 方法创建一个内容与此缓冲区相同的新 `ArrayBuffer` 实例，然后将此缓冲区分离。 + +## 语法 + +```js-nolint +transfer() +transfer(newByteLength) +``` + +### 参数 + +- `newByteLength` {{optional_inline}} + - : 新的 `ArrayBuffer` 的 {{jsxref("ArrayBuffer/byteLength", "byteLength")}}。默认为此 `ArrayBuffer` 的 `byteLength`。 + - 如果 `newByteLength` 小于此 `ArrayBuffer` 的 `byteLength`，“溢出”的字节将被丢弃。 + - 如果 `newByteLength` 大于此 `ArrayBuffer` 的 `byteLength`，剩下的的字节将用零填充。 + - 如果此 `ArrayBuffer` 是可调整大小的，`newByteLength` 一定不能大于其 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}}。 + +### 返回值 + +一个新的 {{jsxref("ArrayBuffer")}} 对象。其内容被初始化为此 `ArrayBuffer` 的内容，如果有额外的字节。则填充为零。当且仅当此 `ArrayBuffer` 是可调整大小的，新 `ArrayBuffer` 才是可调整大小的，在这种情况下，其 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} 和此 `ArrayBuffer` 的相同。原始 `ArrayBuffer` 将被分离。 + +### 异常 + +- {{jsxref("RangeError")}} + - : 如果此 `ArrayBuffer` 是可调整大小的并且 `newByteLength` 大于此 `ArrayBuffer` 的 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}}，则抛出此错误。 +- {{jsxref("TypeError")}} + - : 如果此 `ArrayBuffer` 已经分离，则抛出此错误。 + +## 描述 + +`transfer()` 方法执行与[结构化克隆算法](/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)相同的操作。它将此 `ArrayBuffer` 的字节复制到一个新的 `ArrayBuffer` 对象中，然后分离此 `ArrayBuffer` 对象。有关更多信息，请参阅[传输 ArrayBuffers](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#传输_arraybuffer)。 + +`transfer()` 保留了此 `ArrayBuffer` 的大小可调整性。如果你希望新的 `ArrayBuffer` 不可调整大小，请使用 {{jsxref("ArrayBuffer/transferToFixedLength", "transferToFixedLength()")}} 代替。没有办法通过传输使长度固定的缓冲区变为可调整大小的缓冲区。 + +`transfer()` 是非常高效的，因为（引擎）实现可能以零拷贝移动或 `realloc`——没有实际数据的复制——来实现此方法。 + +## 示例 + +### 传输一个 ArrayBuffer + +```js +// 创建一个 ArrayBuffer 并写入一些字节 +const buffer = new ArrayBuffer(8); +const view = new Uint8Array(buffer); +view[1] = 2; +view[7] = 4; + +// 将缓冲区复制到另一个相同大小的缓冲区 +const buffer2 = buffer.transfer(); +console.log(buffer.detached); // true +console.log(buffer2.byteLength); // 8 +const view2 = new Uint8Array(buffer2); +console.log(view2[1]); // 2 +console.log(view2[7]); // 4 + +// 将缓冲区复制到一个更小的缓冲区 +const buffer3 = buffer2.transfer(4); +console.log(buffer3.byteLength); // 4 +const view3 = new Uint8Array(buffer3); +console.log(view3[1]); // 2 +console.log(view3[7]); // undefined + +// 将缓冲区复制到一个更大的缓冲区 +const buffer4 = buffer3.transfer(8); +console.log(buffer4.byteLength); // 8 +const view4 = new Uint8Array(buffer4); +console.log(view4[1]); // 2 +console.log(view4[7]); // 0 + +// 已经分离，抛出 TypeError +buffer.transfer(); // TypeError: Cannot perform ArrayBuffer.prototype.transfer on a detached ArrayBuffer +``` + +### 传输一个可调整大小的 ArrayBuffer + +```js +const buffer = new ArrayBuffer(8, { maxByteLength: 16 }); +const view = new Uint8Array(buffer); +view[1] = 2; +view[7] = 4; + +// 将缓冲区复制到一个更小的缓冲区 +const buffer2 = buffer.transfer(4); +console.log(buffer2.byteLength); // 4 +console.log(buffer2.maxByteLength); // 16 +const view2 = new Uint8Array(buffer2); +console.log(view2[1]); // 2 +console.log(view2[7]); // undefined +buffer2.resize(8); +console.log(view2[7]); // 0 + +// 将缓冲区复制到一个大小在 maxByteLength 內但更大的缓冲区 +const buffer3 = buffer2.transfer(12); +console.log(buffer3.byteLength); // 12 + +// 将缓冲区复制到一个大小超过 maxByteLength 的更大的缓冲区 +buffer3.transfer(20); // RangeError: Invalid array buffer length +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- {{jsxref("ArrayBuffer")}} +- {{jsxref("ArrayBuffer.prototype.detached")}} +- {{jsxref("ArrayBuffer.prototype.transferToFixedLength()")}} From 863b4f9e5ad7459ea9d19a02cdfe8faf4e154975 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Tue, 28 Nov 2023 09:51:43 +0800 Subject: [PATCH 2/4] Apply suggestions from code review --- .../global_objects/arraybuffer/transfer/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md index d21a790b7998f3..f8f7f756c9f50f 100644 --- a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md +++ b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md @@ -7,7 +7,7 @@ l10n: {{JSRef}} {{SeeCompatTable}} -{{jsxref("ArrayBuffer")}} 实例的 **`transfer()`** 方法创建一个内容与此缓冲区相同的新 `ArrayBuffer` 实例，然后将此缓冲区分离。 +{{jsxref("ArrayBuffer")}} 实例的 **`transfer()`** 方法创建一个内容与该缓冲区相同的新 `ArrayBuffer` 实例，然后将当前缓冲区分离。 ## 语法 @@ -19,10 +19,10 @@ transfer(newByteLength) ### 参数 - `newByteLength` {{optional_inline}} - - : 新的 `ArrayBuffer` 的 {{jsxref("ArrayBuffer/byteLength", "byteLength")}}。默认为此 `ArrayBuffer` 的 `byteLength`。 - - 如果 `newByteLength` 小于此 `ArrayBuffer` 的 `byteLength`，“溢出”的字节将被丢弃。 - - 如果 `newByteLength` 大于此 `ArrayBuffer` 的 `byteLength`，剩下的的字节将用零填充。 - - 如果此 `ArrayBuffer` 是可调整大小的，`newByteLength` 一定不能大于其 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}}。 + - : 新的 `ArrayBuffer` 的 {{jsxref("ArrayBuffer/byteLength", "byteLength")}}。默认为当前 `ArrayBuffer` 的 `byteLength`。 + - 如果 `newByteLength` 小于当前 `ArrayBuffer` 的 `byteLength`，“溢出”的字节将被丢弃。 + - 如果 `newByteLength` 大于当前 `ArrayBuffer` 的 `byteLength`，剩下的的字节将用零填充。 + - 如果当前的 `ArrayBuffer` 是可调整大小的，`newByteLength` 一定不能大于其 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}}。 ### 返回值 From c008436ab97c115ac8a9cf7bf8f8833f42e13bdf Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Tue, 28 Nov 2023 10:07:48 +0800 Subject: [PATCH 3/4] Apply suggestions from code review --- .../global_objects/arraybuffer/transfer/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md index f8f7f756c9f50f..0d02993480a58d 100644 --- a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md +++ b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md @@ -26,20 +26,20 @@ transfer(newByteLength) ### 返回值 -一个新的 {{jsxref("ArrayBuffer")}} 对象。其内容被初始化为此 `ArrayBuffer` 的内容，如果有额外的字节。则填充为零。当且仅当此 `ArrayBuffer` 是可调整大小的，新 `ArrayBuffer` 才是可调整大小的，在这种情况下，其 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} 和此 `ArrayBuffer` 的相同。原始 `ArrayBuffer` 将被分离。 +一个新的 {{jsxref("ArrayBuffer")}} 对象。其内容被初始化为当前 `ArrayBuffer` 的内容，如果有额外的字节。则填充为零。当且仅当当前 `ArrayBuffer` 是可调整大小的，新 `ArrayBuffer` 才是可调整大小的，在这种情况下，其 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} 和当前 `ArrayBuffer` 的相同。当前 `ArrayBuffer` 将被分离。 ### 异常 - {{jsxref("RangeError")}} - - : 如果此 `ArrayBuffer` 是可调整大小的并且 `newByteLength` 大于此 `ArrayBuffer` 的 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}}，则抛出此错误。 + - : 如果当前 `ArrayBuffer` 是可调整大小的并且 `newByteLength` 大于当前 `ArrayBuffer` 的 {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}}，则抛出此错误。 - {{jsxref("TypeError")}} - - : 如果此 `ArrayBuffer` 已经分离，则抛出此错误。 + - : 如果当前 `ArrayBuffer` 已经分离，则抛出此错误。 ## 描述 -`transfer()` 方法执行与[结构化克隆算法](/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)相同的操作。它将此 `ArrayBuffer` 的字节复制到一个新的 `ArrayBuffer` 对象中，然后分离此 `ArrayBuffer` 对象。有关更多信息，请参阅[传输 ArrayBuffers](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#传输_arraybuffer)。 +`transfer()` 方法执行与[结构化克隆算法](/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)相同的操作。它将当前 `ArrayBuffer` 的字节复制到一个新的 `ArrayBuffer` 对象中，然后分离当前 `ArrayBuffer` 对象。有关更多信息，请参阅[传输 ArrayBuffers](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#传输_arraybuffer)。 -`transfer()` 保留了此 `ArrayBuffer` 的大小可调整性。如果你希望新的 `ArrayBuffer` 不可调整大小，请使用 {{jsxref("ArrayBuffer/transferToFixedLength", "transferToFixedLength()")}} 代替。没有办法通过传输使长度固定的缓冲区变为可调整大小的缓冲区。 +`transfer()` 保留了当前 `ArrayBuffer` 的大小可调整性。如果你希望新的 `ArrayBuffer` 不可调整大小，请使用 {{jsxref("ArrayBuffer/transferToFixedLength", "transferToFixedLength()")}} 代替。没有办法通过传输使长度固定的缓冲区变为可调整大小的缓冲区。 `transfer()` 是非常高效的，因为（引擎）实现可能以零拷贝移动或 `realloc`——没有实际数据的复制——来实现此方法。 From 9ff3ad70c06925dad4470b148567fd53d5cf9512 Mon Sep 17 00:00:00 2001 From: A1lo Date: Tue, 28 Nov 2023 20:54:02 +0800 Subject: [PATCH 4/4] Update files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md --- .../reference/global_objects/arraybuffer/transfer/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md index 0d02993480a58d..5b4059f469217b 100644 --- a/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md +++ b/files/zh-cn/web/javascript/reference/global_objects/arraybuffer/transfer/index.md @@ -37,7 +37,7 @@ transfer(newByteLength) ## 描述 -`transfer()` 方法执行与[结构化克隆算法](/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)相同的操作。它将当前 `ArrayBuffer` 的字节复制到一个新的 `ArrayBuffer` 对象中，然后分离当前 `ArrayBuffer` 对象。有关更多信息，请参阅[传输 ArrayBuffers](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#传输_arraybuffer)。 +`transfer()` 方法执行与[结构化克隆算法](/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)相同的操作。它将当前 `ArrayBuffer` 的字节复制到一个新的 `ArrayBuffer` 对象中，然后分离当前 `ArrayBuffer` 对象。有关更多信息，请参阅[传输 ArrayBuffer](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#传输_arraybuffer)。 `transfer()` 保留了当前 `ArrayBuffer` 的大小可调整性。如果你希望新的 `ArrayBuffer` 不可调整大小，请使用 {{jsxref("ArrayBuffer/transferToFixedLength", "transferToFixedLength()")}} 代替。没有办法通过传输使长度固定的缓冲区变为可调整大小的缓冲区。