EinTypedArray Objekt beschreibt eine array-ähnliche Ansicht eineszugrunde liegendenbinären Datenpuffers.Es gibt keine globale Eigenschaft namensTypedArray, noch gibt es einendirekt sichtbarenTypedArray Konstruktor. Stattdessen gibt es eine Anzahl vonunterschiedlichen globalen Eigenschaften, deren Werte getypte Array-Konstruktoren für spezifischeElementtypen sind, wie unten aufgelistet. Auf den folgenden Seiten finden Sie allgemeine Eigenschaften undMethoden, die mit jedem typisierten Array verwendet werden können, das Elemente eines beliebigen Typs enthält.

Beschreibung

DerTypedArray Konstruktor (oft als%TypedArray% bezeichnet, um seine "Intrinsicness" anzuzeigen, da es keine globale Eigenschaft gibt, die in einem JavaScript-Programm sichtbar ist) dient als die gemeinsame Superklasse allerTypedArray Unterklassen. Betrachten Sie%TypedArray% als eine "abstrakte Klasse", die eine gemeinsame Schnittstelle von Dienstmethoden für alle getypten Array-Unterklassen bietet. Dieser Konstruktor ist nicht direkt zugänglich: Es gibt keine globaleTypedArray Eigenschaft. Er ist nur überObject.getPrototypeOf(Int8Array) und ähnliche Zugriffe verfügbar.

Beim Erstellen einer Instanz einerTypedArray Unterklasse (z.B.Int8Array) wird intern im Speicher ein Array-Puffer erstellt oder, wenn einArrayBuffer Objekt als Konstruktorargument übergeben wird, wird dieserArrayBuffer stattdessen verwendet. Die Pufferadresse wird als interne Eigenschaft der Instanz gespeichert und alle Methoden von%TypedArray%.prototype setzen und rufen Werte auf Basis dieser Array-Pufferadresse ab.

TypedArray Objekte

Wertkodierung und Normalisierung

Alle typisierten Arrays arbeiten mitArrayBuffers, in denen Sie die genaue Byte-Darstellung jedes Elements beobachten können. Wie die Zahlen im Binärformat kodiert werden, ist daher wichtig.

• Nicht signierte Ganzzahl-Arrays (Uint8Array,Uint16Array,Uint32Array undBigUint64Array) speichern die Zahl direkt im Binärformat.

• Signierte Ganzzahl-Arrays (Int8Array,Int16Array,Int32Array undBigInt64Array) speichern die Zahl mitZweierkomplement.

• Gleitkomma-Arrays (Float16Array,Float32Array undFloat64Array) speichern die Zahl imIEEE 754 Gleitkommaformat. Die Referenz zuNumber enthält mehr Informationen über das genaue Format. JavaScript-Zahlen verwenden standardmäßig doppelgenaue Gleitkommazahlen, die dasselbe Format wieFloat64Array haben.Float32Array verwendet 23 (anstatt 52) Bits für die Mantisse und 8 (anstatt 11) Bits für den Exponenten.Float16Array verwendet 10 Bits für die Mantisse und 5 Bits für den Exponenten. Beachten Sie, dass die Spezifikation erfordert, dass alleNaN Werte dieselbe Bit-Kodierung verwenden, aber das genaue Bitmuster ist implementierungsabhängig.

• Uint8ClampedArray ist ein Sonderfall. Es speichert die Zahl binär wieUint8Array, klemmt jedoch eine außerhalb des Bereichs liegende Zahl in den Bereich 0 bis 255 auf mathematischem Wege, statt die bedeutendsten Bits abzuschneiden.

Alle typisierten Arrays speichern mit Ausnahme vonInt8Array,Uint8Array undUint8ClampedArray jedes Element mit mehreren Bytes. Diese Bytes können entweder von den bedeutendsten zu den am wenigsten bedeutenden (big-endian) oder von den am wenigsten bedeutenden zu den bedeutendsten (little-endian) geordnet werden. SieheEndianness für mehr Erklärungen. Typisierte Arrays verwenden immer die native Byte-Reihenfolge der Plattform. Wenn Sie die Endianness beim Schreiben und Lesen von Puffern angeben möchten, sollten Sie stattdessen einenDataView verwenden.

Beim Schreiben in diese typisierten Arrays werden Werte, die außerhalb des darstellbaren Bereichs liegen, normalisiert.

• Alle Ganzzahl-Arrays (außerUint8ClampedArray) verwendenfixed-width number conversion, die zuerst den Dezimalteil der Zahl abschneidet und dann die niedrigsten Bits nimmt.
• Uint8ClampedArray klemmt die Zahl zunächst in den Bereich 0 bis 255 (Werte über 255 werden zu 255 und Werte unter 0 werden zu 0). Esrundet dann (statt den Boden zu nehmen) das Ergebnis zur nächsten ganzen Zahl, mit halbem Wert zu gerader Zahl; das heißt, wenn die Zahl genau zwischen zwei ganzen Zahlen liegt, rundet sie zur nächsten geraden Zahl. Zum Beispiel wird0.5 zu0,1.5 zu2, und2.5 zu2.
• Float16Array undFloat32Array führen ein "round to even" durch, um 64-Bit-Gleitkommazahlen in 32-Bit und 16-Bit zu konvertieren. Dies ist derselbe Algorithmus wie vonMath.fround() undMath.f16round() bereitgestellt.

Verhalten beim Anzeigen eines anpassbaren Puffers

Wenn einTypedArray als Ansicht einesanpassbaren Puffers erstellt wird, hat die Größenanpassung des zugrundeliegenden Puffers unterschiedliche Auswirkungen auf die Größe desTypedArray, abhängig davon, ob dasTypedArray als Längenverfolgungskonstruktion erstellt wird.

Wird ein getyptes Array ohne eine konkrete Größe erstellt, indem der dritte Parameter weggelassen oderundefined übergeben wird, wird das getypte Arraylängenverfolgend und passt sich mit der Größenänderung des darunterliegendenbuffer automatisch an:

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });const float32 = new Float32Array(buffer);console.log(float32.byteLength); // 8console.log(float32.length); // 2buffer.resize(12);console.log(float32.byteLength); // 12console.log(float32.length); // 3

Wenn ein getyptes Array mit einer konkreten Größe unter Verwendung des drittenlength Parameters erstellt wird, passt es sich nicht an, um denbuffer zu enthalten, wenn dieser wächst:

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });const float32 = new Float32Array(buffer, 0, 2);console.log(float32.byteLength); // 8console.log(float32.length); // 2console.log(float32[0]); // 0, the initial valuebuffer.resize(12);console.log(float32.byteLength); // 8console.log(float32.length); // 2console.log(float32[0]); // 0, the initial value

Wird einbuffer verkleinert, kann das betrachtete getypte Array aus den Grenzen geraten, in welchem Fall die beobachtete Größe des typisierten Arrays auf 0 reduziert wird. Dies ist der einzige Fall, in dem sich die Länge eines nicht längenverfolgenden typisierten Arrays ändern kann.

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });const float32 = new Float32Array(buffer, 0, 2);buffer.resize(7);console.log(float32.byteLength); // 0console.log(float32.length); // 0console.log(float32[0]); // undefined

Wächst derbuffer anschließend wieder, um das typisierte Array wieder in die Grenzen zu bringen, wird die Größe des typisierten Arrays auf den ursprünglichen Wert zurückgesetzt.

buffer.resize(8);console.log(float32.byteLength); // 8console.log(float32.length); // 2console.log(float32[0]); // 0 - back in bounds again!

Das gleiche kann auch bei längengleitenden getypten Arrays passieren, wenn der Puffer über diebyteOffset hinaus verkleinert wird.

const buffer = new ArrayBuffer(8, { maxByteLength: 16 });const float32 = new Float32Array(buffer, 4);// float32 is length-tracking, but it only extends from the 4th byte// to the end of the buffer, so if the buffer is resized to be shorter// than 4 bytes, the typed array will become out of boundsbuffer.resize(3);console.log(float32.byteLength); // 0

Konstruktor

Dieses Objekt kann nicht direkt instanziiert werden - der Versuch, es mitnew zu konstruieren, wirft einenTypeError.

new (Object.getPrototypeOf(Int8Array))();// TypeError: Abstract class TypedArray not directly constructable

Stattdessen erstellen Sie eine Instanz eines typisierten Arrays eines bestimmten Typs, wie z.B. einInt8Array oder einBigInt64Array. Diese Objekte haben alle eine gemeinsame Syntax für ihre Konstruktoren:

new TypedArray()new TypedArray(length)new TypedArray(typedArray)new TypedArray(object)new TypedArray(buffer)new TypedArray(buffer, byteOffset)new TypedArray(buffer, byteOffset, length)

WobeiTypedArray ein Konstruktor für einen der konkreten Typen ist.

Parameter

typedArray

Wird es mit einer Instanz einerTypedArray Unterklasse aufgerufen, wird dastypedArray in ein neues typisiertes Array kopiert. Für einen nichtbigintTypedArray Konstruktor kann dertypedArray Parameter nur eines der nichtbigint Typen sein (wieInt32Array). Ebenso kann für einenbigintTypedArray Konstruktor (BigInt64Array oderBigUint64Array) dertypedArray Parameter nur einer derbigint Typen sein. Jeder Wert intypedArray wird in den korrespondierenden Typ des Konstruktors konvertiert, bevor er in das neue Array kopiert wird. Die Länge des neuen typisierten Arrays wird dieselbe sein wie die Länge destypedArray Arguments.

object

Wird es mit einem Objekt aufgerufen, das keineTypedArray Instanz ist, wird ein neues typisiertes Array auf die gleiche Weise erstellt wie die MethodeTypedArray.from().

lengthOptional

Wird es mit einer nicht-objekthaften Angabe aufgerufen, wird der Parameter als Zahl behandelt, die die Länge des typisierten Arrays angibt. Ein internes Array-Puffer wird im Speicher erstellt, dessen Größe das Produkt auslength undBYTES_PER_ELEMENT Bytes ist, gefüllt mit Nullen. Das Weglassen aller Parameter entspricht der Verwendung von0 alslength.

buffer,byteOffsetOptional,lengthOptional

Wird es mit einer Instanz vonArrayBuffer oderSharedArrayBuffer aufgerufen und optional einesbyteOffset und eineslength Arguments, wird eine neue typisierte Array-Ansicht erstellt, die den angegebenen Puffer anzeigt. Die ParameterbyteOffset (in Bytes) undlength (in Anzahl der Elemente, die jeweilsBYTES_PER_ELEMENT Bytes belegen) spezifizieren den Speicherbereich, der durch die typisierte Array-Ansicht angezeigt wird. Wenn beide weggelassen werden, wird der gesamtebuffer angezeigt; wenn nurlength weggelassen wird, wird der verbleibendebuffer ab dembyteOffset angezeigt. Wirdlength weggelassen, wird das typisierte Arraylängenverfolgend.

Ausnahmen

Alle Konstruktoren derTypedArray Unterklasse arbeiten auf die gleiche Weise. Sie alle würden die folgenden Ausnahmen werfen:

TypeError

Wird in einem der folgenden Fälle geworfen:

• EintypedArray wird übergeben, aber es ist einbigint Typ, während der aktuelle Konstruktor es nicht ist, oder umgekehrt.
• EintypedArray wird übergeben, aber der Puffer, den es anzeigt, ist getrennt, oder ein getrenntesbuffer wird direkt übergeben.

RangeError

Wird in einem der folgenden Fälle geworfen:

• Die neue Länge des typisierten Arrays ist zu groß.
• Die Länge vonbuffer (wenn derlength Parameter nicht angegeben ist) oderbyteOffset ist kein ganzzahliges Vielfaches der Größe des neuen typisierten Arrays.
• byteOffset ist kein gültiger Array-Index (eine Ganzzahl zwischen 0 und 2⁵³ - 1).
• Beim Erstellen einer Ansicht aus einem Puffer liegen die Grenzen außerhalb des Puffers, d.h.byteOffset + length * TypedArray.BYTES_PER_ELEMENT > buffer.byteLength.

Statische Eigenschaften

Diese Eigenschaften sind auf demTypedArray Konstruktorobjekt definiert und werden daher von allen Konstruktoren derTypedArray Unterklasse geteilt.

TypedArray[Symbol.species]

Die Konstruktorfunktion, die verwendet wird, um abgeleitete Objekte zu erstellen.

AlleTypedArray Unterklassen haben auch die folgenden statischen Eigenschaften:

TypedArray.BYTES_PER_ELEMENT

Gibt einen Zahlenwert der Elementgröße für die verschiedenenTypedArray Objekte zurück.

Statische Methoden

Diese Methoden sind auf demTypedArray Konstruktorobjekt definiert und werden daher von allen Konstruktoren derTypedArray Unterklasse geteilt.

TypedArray.from()

Erzeugt ein neuesTypedArray aus einem array-ähnlichen oder iterierbaren Objekt. Siehe auchArray.from().

TypedArray.of()

Erzeugt ein neuesTypedArray mit einer variablen Anzahl an Argumenten. Siehe auchArray.of().

Instanz-Eigenschaften

Diese Eigenschaften sind aufTypedArray.prototype definiert und werden von allen Instanzen derTypedArray Unterklasse geteilt.

TypedArray.prototype.buffer

Gibt denArrayBuffer zurück, auf den das typisierte Array verweist.

TypedArray.prototype.byteLength

Gibt die Länge (in Bytes) des typisierten Arrays zurück.

TypedArray.prototype.byteOffset

Gibt den Offset (in Bytes) des typisierten Arrays vom Anfang seinesArrayBuffer zurück.

TypedArray.prototype.constructor

Die Konstruktionsfunktion, die das Instanzobjekt erstellt hat.TypedArray.prototype.constructor ist die versteckteTypedArray Konstruktionsfunktion, aber jede Unterklasse des typisierten Arrays definiert ebenfalls ihre eigeneconstructor Eigenschaft.

TypedArray.prototype.length

Gibt die Anzahl der im typisierten Array enthaltenen Elemente zurück.

TypedArray.prototype[Symbol.toStringTag]

Der anfängliche Wert derTypedArray.prototype[Symbol.toStringTag] Eigenschaft ist ein Getter, der denselben String wie der Name des Konstruktors des typisierten Arrays zurückgibt. Er gibtundefined zurück, falls derthis Wert nicht einer der Unterklassen des typisierten Arrays ist. Diese Eigenschaft wird inObject.prototype.toString() verwendet. DaTypedArray jedoch auch eine eigenetoString() Methode hat, wird diese Eigenschaft nicht verwendet, es sei denn, Sie rufenObject.prototype.toString.call() mit einem typisierten Array alsthisArg auf.

AlleTypedArray Unterklassen haben auch die folgenden Instanz-Eigenschaften:

TypedArray.prototype.BYTES_PER_ELEMENT

Gibt einen Zahlenwert der Elementgröße für die verschiedenenTypedArray Objekte zurück.

Instanz-Methoden

Diese Methoden sind auf demTypedArray Prototypobjekt definiert und werden daher von allen Instanzen derTypedArray Unterklasse geteilt.

TypedArray.prototype.at()

Nimmt einen ganzzahligen Wert und gibt das Element an diesem Index zurück. Diese Methode erlaubt negative Ganzzahlen, die rückwärts vom letzten Element zählen.

TypedArray.prototype.copyWithin()

Kopiert eine Sequenz von Array-Elementen innerhalb des Arrays. Siehe auchArray.prototype.copyWithin().

TypedArray.prototype.entries()

Gibt ein neuesArray-Iteratoren Objekt zurück, das die Schlüssel/Wert-Paare für jeden Index im Array enthält. Siehe auchArray.prototype.entries().

TypedArray.prototype.every()

Gibtfalse zurück, wenn es ein Element im Array findet, das die bereitgestellte Testfunktion nicht erfüllt. Andernfalls gibt estrue zurück. Siehe auchArray.prototype.every().

TypedArray.prototype.fill()

Füllt alle Elemente eines Arrays vom Startindex bis zum Endindex mit einem statischen Wert. Siehe auchArray.prototype.fill().

TypedArray.prototype.filter()

Erstellt ein neues Array mit allen Elementen dieses Arrays, für die die bereitgestellte Filterfunktiontrue zurückgibt. Siehe auchArray.prototype.filter().

TypedArray.prototype.find()

Gibt das ersteelement im Array zurück, das eine bereitgestellte Testfunktion erfüllt, oderundefined, wenn kein geeignetes Element gefunden wird. Siehe auchArray.prototype.find().

TypedArray.prototype.findIndex()

Gibt den ersten Indexwert im Array zurück, der ein Element hat, das eine bereitgestellte Testfunktion erfüllt, oder-1, wenn kein geeignetes Element gefunden wird. Siehe auchArray.prototype.findIndex().

TypedArray.prototype.findLast()

Gibt den Wert des letzten Elements im Array zurück, das eine bereitgestellte Testfunktion erfüllt, oderundefined, wenn kein geeignetes Element gefunden wird. Siehe auchArray.prototype.findLast().

TypedArray.prototype.findLastIndex()

Gibt den Index des letzten Elements im Array zurück, das eine bereitgestellte Testfunktion erfüllt, oder-1, wenn kein geeignetes Element gefunden wird. Siehe auchArray.prototype.findLastIndex().

TypedArray.prototype.forEach()

Ruft eine Funktion für jedes Element im Array auf. Siehe auchArray.prototype.forEach().

TypedArray.prototype.includes()

Bestimmt, ob ein typisiertes Array ein bestimmtes Element enthält und gibt je nach Falltrue oderfalse zurück. Siehe auchArray.prototype.includes().

TypedArray.prototype.indexOf()

Gibt den ersten (niedrigsten) Index eines Elements im Array zurück, der dem angegebenen Wert gleich ist, oder-1, wenn keiner gefunden wird. Siehe auchArray.prototype.indexOf().

TypedArray.prototype.join()

Verbindet alle Elemente eines Arrays zu einem String. Siehe auchArray.prototype.join().

TypedArray.prototype.keys()

Gibt einen neuen Array-Iterator zurück, der die Schlüssel für jeden Index im Array enthält. Siehe auchArray.prototype.keys().

TypedArray.prototype.lastIndexOf()

Gibt den letzten (höchsten) Index eines Elements im Array zurück, der dem angegebenen Wert gleich ist, oder-1, wenn keiner gefunden wird. Siehe auchArray.prototype.lastIndexOf().

TypedArray.prototype.map()

Erstellt ein neues Array mit den Ergebnissen, die durch Aufrufen einer bereitgestellten Funktion für jedes Element in diesem Array entstanden sind. Siehe auchArray.prototype.map().

TypedArray.prototype.reduce()

Wendet eine Funktion auf einen Akkumulator und jeden Wert des Arrays an (von links nach rechts), um es auf einen einzigen Wert zu reduzieren. Siehe auchArray.prototype.reduce().

TypedArray.prototype.reduceRight()

Wendet eine Funktion auf einen Akkumulator und jeden Wert des Arrays an (von rechts nach links), um es auf einen einzigen Wert zu reduzieren. Siehe auchArray.prototype.reduceRight().

TypedArray.prototype.reverse()

Kehrt die Reihenfolge der Elemente eines Arrays um — das erste wird zum letzten und das letzte zum ersten. Siehe auchArray.prototype.reverse().

TypedArray.prototype.set()

Speichert mehrere Werte im typisierten Array, indem Eingabewerte aus einem bestimmten Array gelesen werden.

TypedArray.prototype.slice()

Extrahiert einen Abschnitt eines Arrays und gibt ein neues Array zurück. Siehe auchArray.prototype.slice().

TypedArray.prototype.some()

Gibttrue zurück, wenn es ein Element im Array findet, das die bereitgestellte Testfunktion erfüllt. Andernfalls gibt esfalse zurück. Siehe auchArray.prototype.some().

TypedArray.prototype.sort()

Sortiert die Elemente eines Arrays an Ort und Stelle und gibt das Array zurück. Siehe auchArray.prototype.sort().

TypedArray.prototype.subarray()

Gibt ein neuesTypedArray aus dem angegebenen Start- und Endelement-Index zurück.

TypedArray.prototype.toLocaleString()

Gibt einen lokalisierten String zurück, der das Array und seine Elemente darstellt. Siehe auchArray.prototype.toLocaleString().

TypedArray.prototype.toReversed()

Gibt ein neues Array mit den Elementen in umgekehrter Reihenfolge zurück, ohne das ursprüngliche Array zu verändern.

TypedArray.prototype.toSorted()

Gibt ein neues Array mit den Elementen in aufsteigender Reihenfolge sortiert zurück, ohne das ursprüngliche Array zu verändern.

TypedArray.prototype.toString()

Gibt einen String zurück, der das Array und seine Elemente darstellt. Siehe auchArray.prototype.toString().

TypedArray.prototype.values()

Gibt ein neuesArray-Iteratoren Objekt zurück, das die Werte für jeden Index im Array enthält. Siehe auchArray.prototype.values().

TypedArray.prototype.with()

Gibt ein neues Array zurück, bei dem das Element an dem gegebenen Index durch den gegebenen Wert ersetzt wird, ohne das ursprüngliche Array zu modifizieren.

TypedArray.prototype[Symbol.iterator]()

Gibt ein neuesArray-Iteratoren Objekt zurück, das die Werte für jeden Index im Array enthält.

Beispiele

Property-Zugriff

Sie können auf Elemente im Array mit der Standard-Array-Indexsyntax zugreifen (das heißt,unter Verwendung der Klammernotation). Beim Abrufen oder Setzen von indizierten Eigenschaften in typisierten Arrayswird jedoch nicht in der Prototypenkette nach dieser Eigenschaft gesucht, sogar wenn die Indizes außerhalbder Grenzen liegen. Indizierte Eigenschaften konsultieren denArrayBuffer undwerden niemals Objekteigenschaften betrachten. Sie können weiterhin benannte Eigenschaften verwenden, genau wie bei allenObjekten.

// Setting and getting using standard array syntaxconst int16 = new Int16Array(2);int16[0] = 42;console.log(int16[0]); // 42// Indexed properties on prototypes are not consulted (Fx 25)Int8Array.prototype[20] = "foo";new Int8Array(32)[20]; // 0// even when out of boundInt8Array.prototype[20] = "foo";new Int8Array(8)[20]; // undefined// or with negative integersInt8Array.prototype[-1] = "foo";new Int8Array(8)[-1]; // undefined// Named properties are allowed, though (Fx 30)Int8Array.prototype.foo = "bar";new Int8Array(32).foo; // "bar"

Kann nicht eingefroren werden

TypedArrays, die nicht leer sind, können nicht eingefroren werden, da ihrzugrunde liegenderArrayBuffer durch eine andereTypedArray Ansicht des Puffers verändert werden könnte. Dies würde bedeuten, dass das Objektniemals wirklich eingefroren wäre.

const i8 = Int8Array.of(1, 2, 3);Object.freeze(i8);// TypeError: Cannot freeze array buffer views with elements

ByteOffset muss ausgerichtet sein

Beim Erstellen einesTypedArray als Ansicht auf einemArrayBuffer muss dasbyteOffset Argument auf seineElementgröße ausgerichtet sein; mit anderen Worten, der Offset muss ein VielfachesvonBYTES_PER_ELEMENT sein.

const i32 = new Int32Array(new ArrayBuffer(4), 1);// RangeError: start offset of Int32Array should be a multiple of 4

const i32 = new Int32Array(new ArrayBuffer(4), 0);

ByteLength muss ausgerichtet sein

Ebenso wie derbyteOffset Parameter muss auch diebyteLength Eigenschaft einesArrayBuffer, der an den Konstruktor einesTypedArray übergeben wird,ein Vielfaches vonBYTES_PER_ELEMENT des Konstruktors sein.

const i32 = new Int32Array(new ArrayBuffer(3));// RangeError: byte length of Int32Array should be a multiple of 4

const i32 = new Int32Array(new ArrayBuffer(4));

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill von typisierten Arrays incore-js
• JavaScript typisierte Arrays Leitfaden
• ArrayBuffer
• DataView
• TextDecoder