大网数据广告活动
Web 标准与前端开发

ArrayBuffer.prototype.transfer()

· 52CE 我爱测

ArrayBuffer 实例的 **`transfer()`** 方法创建一个内容与该缓冲区相同的新 `ArrayBuffer` 实例,然后将当前缓冲区分离。

ArrayBuffer 实例的 transfer() 方法创建一个内容与该缓冲区相同的新 ArrayBuffer 实例,然后将当前缓冲区分离。

语法

transfer()
transfer(newByteLength)

参数

  • newByteLength
    • : 新的 ArrayBuffer 的 ArrayBuffer/byteLength。默认为当前 ArrayBuffer 的 byteLength。
      • 如果 newByteLength 小于当前 ArrayBuffer 的 byteLength,“溢出”的字节将被丢弃。
      • 如果 newByteLength 大于当前 ArrayBuffer 的 byteLength,剩下的字节将用零填充。
      • 如果当前的 ArrayBuffer 是可调整大小的,newByteLength 一定不能大于其 ArrayBuffer/maxByteLength。

返回值

一个新的 ArrayBuffer 对象。其内容被初始化为当前 ArrayBuffer 的内容,如果有额外的字节。则填充为零。当且仅当当前 ArrayBuffer 是可调整大小的,新 ArrayBuffer 才是可调整大小的,在这种情况下,其 ArrayBuffer/maxByteLength 和当前 ArrayBuffer 的相同。当前 ArrayBuffer 将被分离。

异常

  • RangeError
    • : 如果当前 ArrayBuffer 是可调整大小的并且 newByteLength 大于当前 ArrayBuffer 的 ArrayBuffer/maxByteLength,则抛出此错误。
  • TypeError
    • : 如果当前 ArrayBuffer 已经分离,则抛出此错误。

描述

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

transfer() 保留了当前 ArrayBuffer 的大小可调整性。如果你希望新的 ArrayBuffer 不可调整大小,请使用 ArrayBuffer/transferToFixedLength 代替。没有办法通过传输使长度固定的缓冲区变为可调整大小的缓冲区。

transfer() 是非常高效的,因为(引擎)实现可能以零拷贝移动或 realloc——没有实际数据的复制——来实现此方法。

示例

传输一个 ArrayBuffer

// 创建一个 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

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

规范

浏览器兼容性

参见

  • ArrayBuffer
  • ArrayBuffer.prototype.detached
  • ArrayBuffer.prototype.transferToFixedLength()

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。