TextEncoderStream.encoding — Eigenschaft · JavaScript-Referenz

Signatur

TextEncoderStream.encoding

Beschreibung

Die Eigenschaft encoding eines TextEncoderStream-Objekts gibt als String den Namen des Kodierungsalgorithmus zurück, mit dem der Stream Zeichenketten in Bytes umwandelt. Laut Encoding-Standard kann ein TextEncoderStream nur nach UTF-8 kodieren. Deshalb ist der Wert immer "utf-8".

Der TextEncoderStream ist ein Transform-Stream. Auf seine writable-Seite schreibt man Strings, und auf der readable-Seite kommen Uint8Array-Stücke mit UTF-8-Bytes heraus. Meist nutzt man ihn mit ReadableStream.prototype.pipeThrough(), zum Beispiel um Text zeilenweise an einen Upload per fetch(), in einen CompressionStream oder in eine Datei zu leiten.

Man braucht encoding vor allem in allgemeinem Code, der sowohl Encoder als auch Decoder verarbeitet. Beispiele sind Protokollausgaben, Content-Type-Header (charset=utf-8) und Prüfungen, ob TextDecoderStream und TextEncoderStream zusammenpassen. Die Eigenschaft ist schreibgeschützt: Wer ihr etwas zuweist, ändert nichts.

Rückgabewert

Typ

string

Beschreibung

Der Name der Kodierung, laut Spezifikation immer "utf-8".

Beispiele

Kodierung eines neuen Streams auslesen

const encoderStream = new TextEncoderStream();
console.log(encoderStream.encoding);

utf-8

Text-Stream kodieren und charset im Header setzen

const lines = ['Hallo\n', 'Grüße aus Köln\n'];

const textStream = new ReadableStream({
  start(controller) {
    lines.forEach((line) => controller.enqueue(line));
    controller.close();
  }
});

const encoder = new TextEncoderStream();
const byteStream = textStream.pipeThrough(encoder);

// Header passend zur tatsächlichen Kodierung
const headers = { 'Content-Type': `text/plain; charset=${encoder.encoding}` };
console.log(headers['Content-Type']);

const response = new Response(byteStream);
const bytes = new Uint8Array(await response.arrayBuffer());
console.log(bytes.length);

text/plain; charset=utf-8 28

Encoder und Decoder auf gleiche Kodierung prüfen

const encoder = new TextEncoderStream();
const decoder = new TextDecoderStream('utf-8');

if (encoder.encoding !== decoder.encoding) {
  throw new Error('Kodierungen passen nicht zusammen');
}

const roundTrip = new ReadableStream({
  start(c) { c.enqueue('Ümlaut-Test ✓'); c.close(); }
})
  .pipeThrough(encoder)
  .pipeThrough(decoder);

const text = await new Response(roundTrip.pipeThrough(new TextEncoderStream())).text();
console.log(encoder.encoding, '→', text);

utf-8 → Ümlaut-Test ✓

Schreibschutz der Eigenschaft

'use strict';
const enc = new TextEncoderStream();
try {
  enc.encoding = 'iso-8859-1';
} catch (err) {
  console.log(err instanceof TypeError);
}
console.log(enc.encoding);

true utf-8

// Wichtig · Fallstricke

Nur UTF-8: Der Konstruktor new TextEncoderStream() nimmt kein Kodierungs-Argument an. Andere Zeichensätze wie ISO-8859-1 oder Windows-1252 lassen sich damit nicht erzeugen. Dafür braucht man eigene Kodierer oder Bibliotheken.
Schreibschutz: Die Eigenschaft ist ein reiner Getter. Im nicht-strikten Modus wird eine Zuweisung ohne Meldung ignoriert, im strikten Modus ('use strict', ES-Module) wirft sie einen TypeError.
Kleinschreibung: Der Wert ist immer "utf-8" in Kleinbuchstaben. Wer ihn mit Werten wie "UTF-8" vergleicht, sollte beide Seiten vorher normalisieren (toLowerCase()).
Kompatibilität: Chromium-Browser unterstützen die Eigenschaft seit Version 71, Safari seit 14.1 und Firefox erst seit Version 105. In Node.js ist sie global ab 18 verfügbar, vorher über require('stream/web') (ab 16.6). In älteren Umgebungen kann man einen eigenen TransformStream mit TextEncoder als Ersatz nutzen.
Wie der Eintrag in einem String-Chunk intern aufgeteilt wird (z. B. Surrogat-Paare über Chunk-Grenzen hinweg), handhabt der Stream selbst richtig. Ein einfacher Ersatz mit TextEncoder pro Chunk tut das nicht.

Siehe auch

TextDecoder.ignoreBOM TextEncoderStream.readable TextEncoderStream.writable TextDecoderStream.encoding TextEncoder.encoding