Document.characterSet — Eigenschaft · JavaScript-Referenz

Signatur

get Document.characterSet

Beschreibung

Die schreibgeschützte Eigenschaft document.characterSet liefert den Namen der Zeichenkodierung, die der Browser tatsächlich zum Dekodieren des Dokuments verwendet. Der Wert stammt aus dem Content-Type-HTTP-Header, einem Byte Order Mark (BOM), dem <meta charset>-Element oder – falls nichts davon vorhanden ist – aus der automatischen Erkennung bzw. dem Standard des Browsers.

Zurückgegeben wird immer der kanonische Name laut WHATWG Encoding Standard, z. B. "UTF-8", "windows-1252" oder "Shift_JIS". Schreibt man im Markup etwa <meta charset="latin1"> oder "iso-8859-1", meldet der Browser trotzdem "windows-1252", weil diese Bezeichnungen laut Standard Aliase dafür sind.

Nützlich ist die Eigenschaft vor allem zur Fehlersuche bei Kodierungsproblemen (kaputte Umlaute, „Mojibake“), für Qualitätsprüfungen in Tests oder Monitoring-Skripten sowie beim Arbeiten mit Dokumenten, die per DOMParser, XMLHttpRequest oder in <iframe>s geladen wurden.

Die älteren Eigenschaften document.charset und document.inputEncoding sind reine Aliase von characterSet und sollten in neuem Code nicht mehr verwendet werden.

Rückgabewert

Typ

string

Beschreibung

Der kanonische Name der Zeichenkodierung des Dokuments laut WHATWG Encoding Standard, z. B. "UTF-8" oder "windows-1252".

Beispiele

Aktuelle Kodierung auslesen

// In einer Seite mit <meta charset="utf-8">
console.log(document.characterSet);

UTF-8

Warnung bei falscher Kodierung (QA-Check)

const checkEncoding = (expected = 'UTF-8') => {
  const actual = document.characterSet;
  if (actual.toUpperCase() !== expected.toUpperCase()) {
    console.warn(`Unerwartete Kodierung: ${actual} (erwartet: ${expected})`);
    return false;
  }
  return true;
};

console.log(checkEncoding());

true

Kodierung eines geparsten Dokuments

const parser = new DOMParser();
const doc = parser.parseFromString('<p>Hallo Welt</p>', 'text/html');

// Aus Strings erzeugte Dokumente sind immer UTF-8
console.log(doc.characterSet);

UTF-8

Kodierung eines gleichen-Ursprungs-iframes prüfen

const frame = document.querySelector('iframe');

frame.addEventListener('load', () => {
  try {
    const enc = frame.contentDocument.characterSet;
    console.log(`iframe-Kodierung: ${enc}`);
  } catch (err) {
    // Bei fremdem Ursprung blockiert die Same-Origin-Policy den Zugriff
    console.error('Kein Zugriff auf iframe-Dokument:', err.message);
  }
});

iframe-Kodierung: windows-1252

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wie document.characterSet = 'ISO-8859-1' wird stillschweigend ignoriert (im Strict Mode kein Fehler, da es nur ein Getter ohne Setter ist – der Wert bleibt unverändert). Die Kodierung lässt sich nur über HTTP-Header, BOM oder <meta charset> festlegen.
Kanonische Namen: Der Rückgabewert entspricht nicht unbedingt dem im Markup angegebenen Label (z. B. wird "iso-8859-1" zu "windows-1252"). Vergleiche daher nicht blind gegen den Meta-Wert; bei Bedarf Groß-/Kleinschreibung normalisieren.
Das <meta charset> muss in den ersten 1024 Bytes des Dokuments stehen, sonst erkennt der Browser es möglicherweise nicht und nutzt einen Standardwert.
Der HTTP-Header Content-Type: text/html; charset=… hat Vorrang vor dem Meta-Element; ein BOM hat wiederum Vorrang vor dem Header.
document.charset und document.inputEncoding sind veraltete Aliase – stattdessen characterSet verwenden.
Kompatibilität: In allen modernen Browsern unterstützt; sehr alte Browser lieferten teils kleingeschriebene oder nicht kanonische Namen.

Siehe auch

Document Document.fragmentDirective ProcessingInstruction.sheet Document.anchors Document.children