TextEncoder.encode() — Methode · JavaScript-Referenz

Signatur

TextEncoder.prototype.encode(string)

Beschreibung

Die Methode encode() einer TextEncoder-Instanz wandelt einen JavaScript-String (intern UTF-16) in eine UTF-8-Bytefolge um und gibt sie als neues Uint8Array zurück. TextEncoder unterstützt ausschließlich UTF-8. Andere Kodierungen lassen sich damit nicht erzeugen.

Man braucht die Methode immer dann, wenn Text als Binärdaten weiterverarbeitet werden muss, zum Beispiel beim Hashen mit crypto.subtle.digest(), beim Senden über WebSockets oder fetch mit binärem Body, beim Schreiben in ArrayBuffer-basierte Formate oder beim Ermitteln der tatsächlichen Byte-Länge eines Strings.

Jeder Aufruf legt einen neuen Puffer an. Wenn du oft in einen vorhandenen Puffer schreiben willst, ist TextEncoder.prototype.encodeInto() effizienter, weil dabei keine zusätzliche Allokation anfällt.

Parameter

Name	Typ	Default	Beschreibung
$string	string	""	Der zu kodierende Text. Andere Werte werden per `String()` in einen String umgewandelt. Ohne Argument entsteht ein leeres `Uint8Array`.

Rückgabewert

Typ

Uint8Array

Beschreibung

Ein neues Uint8Array mit den UTF-8-Bytes des Strings.

Beispiele

String in UTF-8-Bytes umwandeln

const encoder = new TextEncoder();
const bytes = encoder.encode('Grüße €');

console.log(bytes);
console.log('Zeichen:', 'Grüße €'.length, '– Bytes:', bytes.length);

Uint8Array(11) [71, 114, 195, 188, 195, 159, 101, 32, 226, 130, 172] Zeichen: 7 – Bytes: 11

SHA-256-Hash eines Textes berechnen

const sha256 = async (text) => {
  const data = new TextEncoder().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 vor dem Speichern prüfen

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

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

console.log(passtInLimit('Hallo Welt'));
console.log(passtInLimit('😀😀😀😀😀'));

true false

Rundreise mit TextDecoder

const bytes = new TextEncoder().encode('Äpfel & Öl');
const text = new TextDecoder().decode(bytes);
console.log(text);

Äpfel & Öl

// Wichtig · Fallstricke

Nur UTF-8: Anders als ältere Entwürfe der Spezifikation nimmt der Konstruktor keinen Kodierungsparameter an, und encoder.encoding ist immer "utf-8". Für Kodierungen wie ISO-8859-1 brauchst du eine Bibliothek.
Einzelne Surrogate: Ungepaarte Surrogate wie '\uD800' werden durch U+FFFD (Bytes EF BF BD) ersetzt. Die Umwandlung ist dann verlustbehaftet.
length ≠ Byte-Länge: string.length zählt UTF-16-Code-Units, nicht Bytes. Die echte Größe liefert encode(str).byteLength.
Performance: Einen TextEncoder einmal anlegen und wiederverwenden. Bei großen oder häufigen Schreibvorgängen in bestehende Puffer ist encodeInto() besser.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workern. In Node.js ist die Klasse seit Version 11 global verfügbar, vorher über require('util').TextEncoder. Der Internet Explorer unterstützt sie nicht.

Siehe auch

Uint8Array FileSystemHandle.remove() new PeriodicSyncEvent() TextEncoder.encodeInto() TextDecoder.decode()