ArrayBuffer.prototype.transfer()

基线 2024

新可用

自从 2024 年 3 月，此功能可在最新的设备和浏览器版本中使用。此功能可能无法在旧设备或浏览器中使用。

transfer() 方法是 ArrayBuffer 实例的方法，它创建了一个新的 ArrayBuffer，其字节内容与当前缓冲区相同，然后分离当前缓冲区。

语法

js
transfer()
transfer(newByteLength)

参数

newByteLength 可选

新 ArrayBuffer 的 byteLength。默认为当前 ArrayBuffer 的 byteLength。

  • 如果 newByteLength 小于当前 ArrayBuffer 的 byteLength，则会丢弃“溢出”的字节。
  • 如果 newByteLength 大于当前 ArrayBuffer 的 byteLength，则会用零填充额外的字节。
  • 如果当前 ArrayBuffer 是可调整大小的，则 newByteLength 必须不大于其 maxByteLength。

返回值

一个新的 ArrayBuffer 对象。其内容初始化为当前 ArrayBuffer 的内容，并且任何额外的字节都用零填充。新 ArrayBuffer 是可调整大小的，当且仅当当前 ArrayBuffer 是可调整大小的时，在这种情况下，其 maxByteLength 与当前 ArrayBuffer 的相同。原始 ArrayBuffer 被分离。

异常

RangeError

如果当前 ArrayBuffer 是可调整大小的，并且 newByteLength 大于当前 ArrayBuffer 的 maxByteLength，则抛出此异常。

TypeError

如果当前 ArrayBuffer 已经被分离，则抛出此异常。

描述

transfer() 方法执行的操作与 结构化克隆算法 相同。它将当前 ArrayBuffer 的字节复制到一个新的 ArrayBuffer 对象中，然后分离当前 ArrayBuffer 对象。有关更多信息，请参阅 传输 ArrayBuffers。

transfer() 保留了当前 ArrayBuffer 的可调整大小性。如果希望新 ArrayBuffer 不可调整大小，请改用 transferToFixedLength()。无法传输缓冲区以使固定长度缓冲区变为可调整大小。

transfer() 非常高效，因为实现可以将此方法实现为零复制移动或 realloc——不需要实际复制数据。

示例

传输 ArrayBuffer

js
// Create an ArrayBuffer and write a few bytes
const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[1] = 2;
view[7] = 4;

// Copy the buffer to the same size
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

// Copy the buffer to a smaller size
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

// Copy the buffer to a larger size
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

// Already detached, throws 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;

// Copy the buffer to a smaller size
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

// Copy the buffer to a larger size within maxByteLength
const buffer3 = buffer2.transfer(12);
console.log(buffer3.byteLength); // 12

// Copy the buffer to a larger size than maxByteLength
buffer3.transfer(20); // RangeError: Invalid array buffer length

规范

规范
ArrayBuffer 传输
# sec-arraybuffer.prototype.transfer

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅