Uint8Array.fromHex() — Methode · JavaScript-Referenz

Signatur

Uint8Array.fromHex(string)

Beschreibung

Uint8Array.fromHex() wandelt einen String aus Hexadezimalziffern (0–9, a–f, A–F) in Binärdaten um. Je zwei Zeichen ergeben ein Byte, zum Beispiel wird "ff" zu 255. Das Ergebnis ist ein neues Uint8Array mit eigenem ArrayBuffer.

Typische Einsatzfälle sind Hash-Werte (SHA-256, MD5), kryptografische Schlüssel und Nonces, Farbwerte oder Byte-Folgen aus Protokollen und Konfigurationsdateien, die als Hex-Text vorliegen. Bisher schrieb man dafür eigene Schleifen mit parseInt(…, 16). Die eingebaute Methode ist kürzer, schneller und prüft die Eingabe streng.

Die Eingabe muss eine gerade Anzahl von Zeichen haben und darf nur Hex-Ziffern enthalten. Leerzeichen, Zeilenumbrüche, Trennzeichen wie : und das Präfix 0x sind nicht erlaubt und lösen einen SyntaxError aus. Groß- und Kleinbuchstaben dürfen gemischt vorkommen. Um Daten in ein bereits vorhandenes Array zu schreiben, verwendest du Uint8Array.prototype.setFromHex(). Für den umgekehrten Weg gibt es Uint8Array.prototype.toHex().

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Hexadezimal-String mit gerader Länge, der nur die Zeichen `0–9`, `a–f` und `A–F` enthält. Ein leerer String ergibt ein leeres Array.

Rückgabewert

Typ

Uint8Array

Beschreibung

Ein neues Uint8Array mit den dekodierten Bytes. Seine Länge ist die halbe Länge des Strings.

Beispiele

Hex-String in Bytes umwandeln

const bytes = Uint8Array.fromHex('cafed00d');
console.log(bytes);
console.log(bytes.length);

// Groß- und Kleinbuchstaben sind beide erlaubt
console.log(Uint8Array.fromHex('FFfF00'));

Uint8Array(4) [ 202, 254, 208, 13 ] 4 Uint8Array(3) [ 255, 255, 0 ]

SHA-256-Prüfsumme mit gespeichertem Hash vergleichen

const expectedHex = '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824';

const verify = async (text) => {
  const data = new TextEncoder().encode(text);
  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', data));
  const expected = Uint8Array.fromHex(expectedHex);
  return digest.length === expected.length &&
    digest.every((byte, i) => byte === expected[i]);
};

console.log(await verify('hello'));
console.log(await verify('Hallo'));

true false

Ungültige Eingaben abfangen und bereinigen

const parseHex = (input) => {
  // Präfix 0x, Leerzeichen und Doppelpunkte vorher entfernen
  const clean = input.replace(/^0x/i, '').replace(/[\s:]/g, '');
  try {
    return Uint8Array.fromHex(clean);
  } catch (err) {
    console.error(`${err.name}: ungültiger Hex-String "${input}"`);
    return null;
  }
};

console.log(parseHex('0xDE:AD:BE:EF'));
parseHex('abc');   // ungerade Länge
parseHex('zz');    // keine Hex-Zeichen

Uint8Array(4) [ 222, 173, 190, 239 ] SyntaxError: ungültiger Hex-String "abc" SyntaxError: ungültiger Hex-String "zz"

Feature-Erkennung mit Fallback

const hexToBytes = (hex) => {
  if (typeof Uint8Array.fromHex === 'function') {
    return Uint8Array.fromHex(hex);
  }
  if (hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex)) {
    throw new SyntaxError('Ungültiger Hex-String');
  }
  const out = new Uint8Array(hex.length / 2);
  for (let i = 0; i < out.length; i++) {
    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
  }
  return out;
};

console.log(hexToBytes('0a0b0c'));

Uint8Array(3) [ 10, 11, 12 ]

// Wichtig · Fallstricke

Strenge Prüfung: Eine ungerade Länge oder ein Zeichen, das keine Hex-Ziffer ist, löst einen SyntaxError aus. Das gilt auch für Leerzeichen, 0x und Trennzeichen. Es gibt keine Teilergebnisse: Entweder wird der ganze String dekodiert oder gar nichts.
Kein String: Andere Werte wie Zahlen, null oder ein ArrayBuffer werden nicht automatisch umgewandelt. Sie lösen einen TypeError aus.
Nur auf Uint8Array: Die Methode gibt es nicht auf anderen TypedArrays wie Uint16Array. Auch Unterklassen von Uint8Array erhalten immer ein einfaches Uint8Array zurück.
Speicher: Bei jedem Aufruf wird ein neuer Puffer angelegt. Für viele Aufrufe hintereinander oder vorher angelegte Puffer ist setFromHex() besser geeignet.
Kompatibilität: Die Methode ist relativ neu (Proposal „Uint8Array to/from Base64 and Hex“, ES2026). Sie ist verfügbar ab Firefox 133, Safari 18.2, Chrome/Edge 140 und in Node.js-Versionen mit einer passenden V8-Engine. Für ältere Umgebungen solltest du die Funktion per Feature-Erkennung prüfen und einen Polyfill (z. B. core-js) oder eine eigene Umwandlung nutzen.
Sicherheit: Wenn du Hashes oder Signaturen vergleichst, reicht ein byteweiser Vergleich wie every() für Integritätsprüfungen. Für geheime Werte wie HMACs solltest du einen Vergleich mit konstanter Laufzeit verwenden, z. B. crypto.timingSafeEqual in Node.js.

Siehe auch

Uint8Array.prototype.toHex() Uint8Array.prototype.setFromHex() Uint8Array.fromBase64() Uint8Array.prototype.toBase64() Uint8Array TextEncoder parseInt()