Document.bgColor — Eigenschaft · JavaScript-Referenz

Signatur

Document.bgColor

Beschreibung

document.bgColor ist ein Überbleibsel aus der Frühzeit des Webs. Die Eigenschaft spiegelt das Inhaltsattribut bgcolor des <body>-Elements wider: Beim Lesen bekommst du den Attributwert als Zeichenkette, beim Schreiben wird das Attribut gesetzt. Gibt es kein <body> (etwa bei einem Frameset oder einem XML-Dokument ohne Body), ist der Wert eine leere Zeichenkette und Zuweisungen bewirken nichts.

Als Wert eignen sich Farbnamen wie "red" oder Hex-Notation wie "#ff0000". Der Rückgabewert wird nicht normalisiert. Du bekommst also genau die Zeichenkette zurück, die im Attribut steht, und nicht den tatsächlich berechneten Farbwert. Setzt du die Hintergrundfarbe per CSS, bekommt bgColor davon nichts mit.

In neuem Code solltest du die Eigenschaft nicht mehr verwenden. Nutze stattdessen document.body.style.backgroundColor oder, besser, CSS-Klassen bzw. benutzerdefinierte Eigenschaften (--variablen). Den tatsächlich wirksamen Wert liest du mit getComputedStyle(document.body).backgroundColor aus. bgColor brauchst du eigentlich nur noch, wenn du alten Code pflegst oder verstehen willst.

Parameter

Name	Typ	Default	Beschreibung
$wert	string	""	Nur beim Schreiben: Farbangabe als Zeichenkette, z. B. `"#ffffff"` oder `"lightblue"`. Der Wert wird unverändert in das `bgcolor`-Attribut von `<body>` geschrieben.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des bgcolor-Attributs von <body>, unverändert und nicht normalisiert. Ist das Attribut nicht gesetzt oder fehlt <body>, ist das Ergebnis eine leere Zeichenkette.

Beispiele

Hintergrundfarbe lesen und setzen

// Wert ohne gesetztes Attribut
console.log(JSON.stringify(document.bgColor));

// Farbe setzen – schreibt das bgcolor-Attribut von <body>
document.bgColor = 'lightblue';
console.log(document.bgColor);
console.log(document.body.getAttribute('bgcolor'));

"" lightblue lightblue

Kein Normalisieren und kein Bezug zu CSS

document.bgColor = '#FF0000';
console.log(document.bgColor); // bleibt genau so, wie er gesetzt wurde

// Tatsächlich wirksame Farbe nur über getComputedStyle
console.log(getComputedStyle(document.body).backgroundColor);

// CSS-Inline-Stil hat Vorrang, bgColor bekommt davon nichts mit
document.body.style.backgroundColor = 'green';
console.log(document.bgColor);
console.log(getComputedStyle(document.body).backgroundColor);

#FF0000 rgb(255, 0, 0) #FF0000 rgb(0, 128, 0)

Alten Code modernisieren: Dark-Mode-Umschalter

// Alt: document.bgColor = dunkel ? '#111111' : '#ffffff';
// Modern: CSS-Klasse umschalten, Farben stehen im Stylesheet
const toggleDarkMode = (dunkel) => {
  document.body.removeAttribute('bgcolor'); // eventuelle Altlasten entfernen
  document.body.classList.toggle('dark', dunkel);
};

toggleDarkMode(true);
console.log(document.body.classList.contains('dark'));

true

// Wichtig · Fallstricke

Veraltet: Die HTML-Spezifikation führt bgColor als obsolet. Alle aktuellen Browser unterstützen die Eigenschaft noch aus Kompatibilitätsgründen, in neuem Code solltest du sie aber nicht verwenden.
Die Eigenschaft liest und schreibt nur das HTML-Attribut bgcolor. Farben aus CSS (Stylesheets oder style) werden nicht erfasst. CSS hat außerdem Vorrang vor dem Attribut.
Die Groß-/Kleinschreibung ist wichtig: Die Eigenschaft heißt bgColor, das Attribut heißt bgcolor. Schreibst du document.bgcolor, legst du nur eine neue, wirkungslose Eigenschaft an.
Ohne <body> (etwa bei einem Frameset oder vor dem Parsen des Body in einem Skript im <head>) werden Zuweisungen stillschweigend ignoriert.
Ungültige Farbwerte werden trotzdem ins Attribut geschrieben. Der Browser wertet sie dann mit dem alten, fehlertoleranten Farb-Parser aus, was zu unerwarteten Farben führen kann.

Siehe auch

Document.fgColor Document.linkColor Document.body HTMLElement.style Window.getComputedStyle() Element.classList HTMLTableElement.bgColor