ArrayBuffer.prototype.transfer()

Baseline 2024

Neu verfügbar

Seit March 2024 funktioniert diese Funktion auf aktuellen Geräten und in aktuellen Browserversionen. Auf älteren Geräten oder in älteren Browsern funktioniert sie möglicherweise nicht.

Die transfer() Methode von ArrayBuffer Instanzen erstellt einen neuen ArrayBuffer mit demselben Byte-Inhalt wie dieser Puffer und trennt dann diesen Puffer ab.

In diesem Artikel

Syntax

js
transfer()
transfer(newByteLength)

Parameter

newByteLength Optional

Der byteLength des neuen ArrayBuffer. Standardmäßig ist dies der byteLength dieses ArrayBuffer.

Wenn newByteLength kleiner als der byteLength dieses ArrayBuffer ist, werden die "überlaufenden" Bytes verworfen.
Wenn newByteLength größer als der byteLength dieses ArrayBuffer ist, werden die zusätzlichen Bytes mit Nullen gefüllt.
Wenn dieser ArrayBuffer vergrößerbar ist, darf newByteLength nicht größer als sein maxByteLength sein.

Ein neues ArrayBuffer Objekt. Sein Inhalt wird auf den Inhalt dieses ArrayBuffer initialisiert, und zusätzliche Bytes, falls vorhanden, werden mit Nullen gefüllt. Der neue ArrayBuffer ist nur dann vergrößerbar, wenn auch dieser ArrayBuffer vergrößerbar ist, in diesem Fall ist sein maxByteLength das gleiche wie das dieses ArrayBuffer. Der ursprüngliche ArrayBuffer wird getrennt.

Ausnahmen

RangeError

Wird ausgelöst, wenn dieser ArrayBuffer vergrößerbar ist und newByteLength größer ist als der maxByteLength dieses ArrayBuffer.

TypeError

Wird ausgelöst, wenn dieser ArrayBuffer bereits getrennt ist oder wenn er nur durch bestimmte Operationen getrennt werden kann. Derzeit sind es nur bestimmte Web-APIs, die in der Lage sind, ArrayBuffer Objekte mit bestimmten Trennmethoden zu erstellen, wie zum Beispiel GPUBuffer.getMappedRange() und WebAssembly.Memory.buffer.

Beschreibung

Die transfer() Methode führt dieselbe Operation wie der Structured Clone Algorithmus aus. Sie kopiert die Bytes dieses ArrayBuffer in ein neues ArrayBuffer Objekt und trennt dann dieses ArrayBuffer Objekt. Weitere Informationen finden Sie unter Übergabe von ArrayBuffers.

transfer() bewahrt die Vergrößerbarkeit dieses ArrayBuffer. Wenn Sie möchten, dass der neue ArrayBuffer nicht vergrößerbar ist, verwenden Sie stattdessen transferToFixedLength(). Es gibt keinen Weg, einen Puffer zu übertragen, der einen Festlängenpuffer vergrößerbar macht.

transfer() ist sehr effizient, da Implementierungen diese Methode als Zero-Copy-Verschiebung oder als realloc implementieren können – es muss keine tatsächliche Kopie der Daten erfolgen.

Beispiele

Ein ArrayBuffer übertragen

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

Einen vergrößerbaren ArrayBuffer übertragen

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

Help improve MDN

War diese Übersetzung hilfreich?

Ja Nein

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden

Eingebaute Standardobjekte
ArrayBuffer
Konstruktor
1. ArrayBuffer()
Statische Methoden
1. isView()
Statische Eigenschaften
1. [Symbol.species]
Instanzmethoden
Instanzeigenschaften
Vererbung
Object/Function
Statische Methoden
Statische Eigenschaften
Instanzmethoden
Instanzeigenschaften
1. __proto__
2. constructor