ArrayBuffer.prototype.transfer()

¥Syntax

transfer()
transfer(newByteLength)

¥Parameters

newByteLength Optional

新款 ArrayBuffer 的 byteLength。默认为该 ArrayBuffer 的 byteLength。

• 如果 newByteLength 小于这个 ArrayBuffer 的 byteLength，则 "overflowing" 字节被丢弃。
• 如果 newByteLength 大于该 ArrayBuffer 的 byteLength，则多余的字节用零填充。
• 如果此 ArrayBuffer 可调整大小，则 newByteLength 不得大于其 maxByteLength。

¥Return value

一个新的 ArrayBuffer 对象。其内容被初始化为该 ArrayBuffer 的内容，并且额外的字节（如果有）用零填充。当且仅当此 ArrayBuffer 是可调整大小时，新的 ArrayBuffer 才可调整大小，在这种情况下，其 maxByteLength 与此 ArrayBuffer 相同。原来的 ArrayBuffer 已分离。

¥A new ArrayBuffer object. Its contents are initialized to the contents of this ArrayBuffer, and extra bytes, if any, are filled with zeros. The new ArrayBuffer is resizable if and only if this ArrayBuffer is resizable, in which case its maxByteLength is the same as this ArrayBuffer's. The original ArrayBuffer is detached.

¥Exceptions

RangeError

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

TypeError

如果此 ArrayBuffer 已分离，则抛出此异常。

¥Description

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

¥The transfer() method performs the same operation as the structured clone algorithm. It copies the bytes of this ArrayBuffer into a new ArrayBuffer object, then detaches this ArrayBuffer object. See transferring ArrayBuffers for more information.

transfer() 保留了 ArrayBuffer 的可调整大小能力。如果你希望新的 ArrayBuffer 不可调整大小，请改用 transferToFixedLength()。没有办法传输使固定长度缓冲区变得可调整大小的缓冲区。

¥transfer() preserves the resizability of this ArrayBuffer. If you want the new ArrayBuffer to be non-resizable, use transferToFixedLength() instead. There's no way to transfer a buffer that makes a fixed-length buffer become resizable.

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

¥transfer() is very efficient because implementations may implement this method as a zero-copy move or a realloc — there does not need to be an actual copy of the data.

¥Examples

¥Transferring an ArrayBuffer

// 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

¥Transferring a resizable ArrayBuffer

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

¥See also

• core-js 中 ArrayBuffer.prototype.transfer() 的 Polyfill
• ArrayBuffer
• ArrayBuffer.prototype.detached
• ArrayBuffer.prototype.transferToFixedLength()