new TextEncoder() — Methode · JavaScript-Referenz

Signatur

new TextEncoder()

Beschreibung

Der Konstruktor TextEncoder() erzeugt einen Kodierer, der JavaScript-Strings (intern UTF-16) in eine Folge von UTF-8-Bytes umwandelt. Die Instanz stellt die Methoden encode() und encodeInto() bereit, außerdem die schreibgeschützte Eigenschaft encoding, die immer "utf-8" liefert.

Man braucht einen TextEncoder immer dann, wenn Text als Binärdaten weiterverarbeitet werden soll: zum Hashen mit der Web Crypto API (crypto.subtle.digest()), zum Verschlüsseln, zum Senden über WebSockets oder WebRTC-Datenkanäle als ArrayBuffer, zum Berechnen der tatsächlichen Byte-Länge eines Strings oder zum Schreiben in Streams und Dateien.

Der Konstruktor nimmt keine Parameter entgegen. Frühere Entwürfe der Spezifikation erlaubten eine Kodierungsangabe (z. B. "utf-16"); dies wurde entfernt. Übergebene Argumente werden ignoriert – für andere Kodierungen gibt es im Standard keinen Encoder, nur für das Dekodieren den TextDecoder.

Eine Instanz ist zustandslos und kann beliebig oft wiederverwendet werden. Es ist daher sinnvoll, einen einzigen Encoder auf Modulebene anzulegen, statt für jeden Aufruf einen neuen zu erzeugen.

Rückgabewert

Typ

TextEncoder

Beschreibung

Ein neues TextEncoder-Objekt mit encoding === "utf-8".

Beispiele

Encoder erzeugen und String kodieren

const encoder = new TextEncoder();
console.log(encoder.encoding);

const bytes = encoder.encode('Grüße €');
console.log(bytes);
console.log(bytes.length);

utf-8 Uint8Array(11) [71, 114, 195, 188, 195, 159, 101, 32, 226, 130, 172] 11

SHA-256-Hash eines Strings mit Web Crypto berechnen

const encoder = new TextEncoder();

const sha256 = async (text) => {
  const data = encoder.encode(text);
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  return [...new Uint8Array(hashBuffer)]
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
};

console.log(await sha256('hallo'));

d3751d33f9cd5049c4af2b462735457e4d3baf130bcbb87f389e349fbaeb20b9

Byte-Länge prüfen, z. B. für ein Server-Limit

const encoder = new TextEncoder();
const MAX_BYTES = 10;

const passtInsLimit = (text) => encoder.encode(text).byteLength <= MAX_BYTES;

console.log('Hallo'.length, passtInsLimit('Hallo'));
console.log('😀😀😀'.length, passtInsLimit('😀😀😀'));

5 true 6 false

In einen vorhandenen Puffer schreiben mit encodeInto()

const encoder = new TextEncoder();
const puffer = new Uint8Array(8);

const { read, written } = encoder.encodeInto('Käsebrot', puffer);
console.log(read, written);
console.log(new TextDecoder().decode(puffer.subarray(0, written)));

7 8 Käsebro

// Wichtig · Fallstricke

Nur UTF-8: Argumente wie new TextEncoder('utf-16') werden stillschweigend ignoriert – das Ergebnis ist trotzdem UTF-8. Für andere Kodierungen wird eine externe Bibliothek benötigt.
Aufruf ohne new (TextEncoder()) wirft einen TypeError.
String-Länge ≠ Byte-Länge: 'ä'.length ist 1, kodiert aber 2 Bytes; Emojis haben length 2 und 4 Bytes.
Einzelne Surrogates (ungültiges UTF-16) werden durch U+FFFD (EF BF BD) ersetzt – es wird kein Fehler geworfen.
Performance: Instanz wiederverwenden; für große oder wiederholte Kodierungen spart encodeInto() Speicherallokationen.
Kompatibilität: In allen modernen Browsern, Web Workern, Deno und Node.js (global ab Version 11, davor über require('util').TextEncoder) verfügbar. Internet Explorer unterstützt die API nicht. Für Streams gibt es zusätzlich TextEncoderStream.

Siehe auch

Uint8Array new DataCue() new TextDecoder() new AudioEncoder() new VideoEncoder()