このページはコミュニティーの尽力で英語から翻訳されました。MDN Web Docsコミュニティーについてもっと知り、仲間になるにはこちらから。
ArrayBuffer.prototype.transfer()
Baseline 2024Newly available
Since March 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
transfer() はArrayBuffer インスタンスのメソッドで、このバッファと同じバイト内容を持つ新しいArrayBuffer を作成し、その後でこのバッファを分離します。
構文
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が既に分離されている場合、または指定された操作によってのみ分離可能な場合に発生します。現在、GPUBuffer.getMappedRange()やWebAssembly.Memory.bufferなどの特定の Web API のみが、指定された分離メソッドを持つArrayBufferオブジェクトを作成できます。
解説
transfer() メソッドは、構造化クローンアルゴリズムと同じ操作を実行します。このArrayBuffer のバイトを新しいArrayBuffer オブジェクトにコピーし、その後このArrayBuffer オブジェクトを分離します。詳細については、ArrayBuffer の移譲を参照してください。
transfer() はこの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); // trueconsole.log(buffer2.byteLength); // 8const view2 = new Uint8Array(buffer2);console.log(view2[1]); // 2console.log(view2[7]); // 4// バッファーをより小さいサイズにコピーconst buffer3 = buffer2.transfer(4);console.log(buffer3.byteLength); // 4const view3 = new Uint8Array(buffer3);console.log(view3[1]); // 2console.log(view3[7]); // undefined// バッファーをより大きなサイズにコピーconst buffer4 = buffer3.transfer(8);console.log(buffer4.byteLength); // 8const view4 = new Uint8Array(buffer4);console.log(view4[1]); // 2console.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); // 4console.log(buffer2.maxByteLength); // 16const view2 = new Uint8Array(buffer2);console.log(view2[1]); // 2console.log(view2[7]); // undefinedbuffer2.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仕様書
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-arraybuffer.prototype.transfer |