ArrayBuffer.prototype.transfer()
Baseline 2024
Newly available
Since March 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
Die transfer()
Methode von ArrayBuffer
Instanzen erstellt einen neuen ArrayBuffer
mit demselben Byte-Inhalt wie dieser Puffer und trennt anschließend diesen Puffer.
Syntax
transfer()
transfer(newByteLength)
Parameter
newByteLength
Optional-
Die
byteLength
des neuenArrayBuffer
. Standardmäßig entspricht sie derbyteLength
diesesArrayBuffer
.- Wenn
newByteLength
kleiner als diebyteLength
diesesArrayBuffer
ist, werden die "überlaufenden" Bytes verworfen. - Wenn
newByteLength
größer als diebyteLength
diesesArrayBuffer
ist, werden die zusätzlichen Bytes mit Nullen gefüllt. - Wenn dieser
ArrayBuffer
anpassbar ist, darfnewByteLength
nicht größer als dessenmaxByteLength
sein.
- Wenn
Rückgabewert
Ein neues ArrayBuffer
Objekt. Der Inhalt wird auf den Inhalt dieses ArrayBuffer
initialisiert, und zusätzliche Bytes, falls vorhanden, werden mit Nullen gefüllt. Der neue ArrayBuffer
ist anpassbar, wenn und nur wenn dieser ArrayBuffer
anpassbar ist, dessen maxByteLength
ist derselbe wie der dieses ArrayBuffer
. Der ursprüngliche ArrayBuffer
wird getrennt.
Ausnahmen
RangeError
-
Wird ausgelöst, wenn dieser
ArrayBuffer
anpassbar ist undnewByteLength
größer ist als diemaxByteLength
diesesArrayBuffer
. TypeError
-
Wird ausgelöst, wenn dieser
ArrayBuffer
bereits getrennt ist.
Beschreibung
Die transfer()
Methode führt die gleiche Operation aus wie der strukturierte Klon-Algorithmus. Sie kopiert die Bytes dieses ArrayBuffer
in ein neues ArrayBuffer
Objekt und trennt anschließend dieses ArrayBuffer
Objekt. Siehe Übertragung von ArrayBuffers für weitere Informationen.
transfer()
erhält die Anpassbarkeit dieses ArrayBuffer
. Wenn Sie möchten, dass der neue ArrayBuffer
nicht anpassbar ist, verwenden Sie stattdessen transferToFixedLength()
. Es gibt keine Möglichkeit, einen Puffer zu übertragen, der einen Puffer mit fester Länge anpassbar macht.
transfer()
ist sehr effizient, da Implementierungen diese Methode als Null-Kopie-Verschiebung oder als realloc
implementieren können — es muss keine tatsächliche Kopie der Daten erfolgen.
Beispiele
Übertragen eines 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
Übertragen eines anpassbaren 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
Spezifikationen
Specification |
---|
ECMAScript Language Specification # sec-arraybuffer.prototype.transfer |
Browser-Kompatibilität
BCD tables only load in the browser