Uint8Array.prototype.toBase64() — Methode · JavaScript-Referenz

Signatur

Uint8Array.prototype.toBase64(options)

Beschreibung

Die Methode toBase64() wandelt den Inhalt eines Uint8Array direkt in einen Base64-String um. Bisher brauchte man dafür den Umweg über btoa(), bei dem die Bytes erst in einen „Binär-String“ übersetzt werden mussten (z. B. mit String.fromCharCode(...bytes)). Das war umständlich, bei großen Puffern langsam und konnte die maximale Anzahl an Funktionsargumenten überschreiten.

Über das Objekt options wählst du das Alphabet: "base64" (Standard, mit + und /) oder "base64url" (mit - und _, sicher in URLs, Dateinamen und JWTs). Mit omitPadding: true werden die abschließenden =-Zeichen weggelassen.

Typische Einsatzfälle sind Data-URLs für Bilder, das Übertragen binärer Daten in JSON, kryptografische Werte (Hashes, Schlüssel, Nonces aus der Web Crypto API) und Token im Base64URL-Format. Das Gegenstück zum Dekodieren ist Uint8Array.fromBase64().

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.alphabet	"base64" \| "base64url"	"base64"	Das verwendete Alphabet. `"base64url"` ersetzt `+` durch `-` und `/` durch `_`.
$options.omitPadding	boolean	false	Bei `true` werden die abschließenden Füllzeichen `=` weggelassen.

Rückgabewert

Typ

string

Beschreibung

Ein Base64-kodierter String mit den Bytes des Arrays. Bei einem leeren Array ist das Ergebnis ein leerer String "".

Beispiele

Einfache Kodierung und UTF-8-Text

const bytes = new Uint8Array([72, 101, 108, 108, 111]);
console.log(bytes.toBase64());

// Text mit Umlauten: erst per TextEncoder nach UTF-8 umwandeln
const utf8 = new TextEncoder().encode("Grüße");
console.log(utf8.toBase64());

SGVsbG8= R3LDvMOfZQ==

URL-sicheres Base64 ohne Füllzeichen (z. B. für Tokens)

const bytes = new Uint8Array([251, 255]);

console.log(bytes.toBase64());
console.log(bytes.toBase64({ alphabet: "base64url", omitPadding: true }));

// Zufälliges, URL-taugliches Token erzeugen
const token = crypto.getRandomValues(new Uint8Array(16))
  .toBase64({ alphabet: "base64url", omitPadding: true });
console.log(token.length);

+/8= -_8 22

Bild als Data-URL einbetten, mit Fallback für ältere Umgebungen

const bytesToBase64 = (bytes) => {
  if (typeof Uint8Array.prototype.toBase64 === "function") {
    return bytes.toBase64();
  }
  // Fallback in Blöcken, damit große Puffer nicht das Argumentlimit sprengen
  let binary = "";
  for (let i = 0; i < bytes.length; i += 0x8000) {
    binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
  }
  return btoa(binary);
};

const loadAsDataUrl = async (url) => {
  const response = await fetch(url);
  const type = response.headers.get("Content-Type") ?? "application/octet-stream";
  const bytes = new Uint8Array(await response.arrayBuffer());
  return `data:${type};base64,${bytesToBase64(bytes)}`;
};

const img = document.querySelector("img");
img.src = await loadAsDataUrl("/logo.png");

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist neu (ES2026). Sie wird von Firefox 133+, Safari 18.2+ und Chrome/Edge 140+ unterstützt, in Node.js erst ab Version 25. Für ältere Umgebungen solltest du prüfen, ob sie vorhanden ist, und auf btoa() oder Buffer.from(bytes).toString(\"base64\") (Node.js) ausweichen.
Die Methode gibt es nur auf Uint8Array, nicht auf anderen TypedArrays wie Uint16Array und auch nicht direkt auf ArrayBuffer. Wickle andere Puffer vorher in new Uint8Array(buffer) ein.
Ein ungültiger Wert für alphabet wirft einen TypeError. Das gilt auch, wenn der zugrunde liegende ArrayBuffer abgelöst (detached) ist, etwa nach einer Übertragung per postMessage.
Base64 ist keine Verschlüsselung. Die Daten lassen sich ohne Schlüssel zurückgewinnen, deshalb solltest du geheime Werte nicht auf diese Weise „verstecken“.
Die Methode kodiert immer den gesamten sichtbaren Bereich des Arrays. Wenn du nur einen Teil kodieren willst, nimm subarray(); das erzeugt eine Ansicht auf dieselben Daten, ohne sie zu kopieren.

Siehe auch

Uint8Array.fromBase64() Uint8Array.prototype.toHex() Uint8Array.prototype.setFromBase64() TextEncoder Uint8Array