CSSKeywordValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSKeywordValue extends CSSStyleValue

Beschreibung

CSSKeywordValue gehört zur CSS Typed Object Model API (Houdini) und erbt von CSSStyleValue. Das Objekt steht für einen CSS-Wert, der aus einem einzelnen Bezeichner besteht, also einem Schlüsselwort wie block, center, transparent oder den CSS-weiten Werten initial, inherit, unset und revert.

Solche Objekte bekommst du, wenn du Werte über element.computedStyleMap(), element.attributeStyleMap oder CSSStyleValue.parse() ausliest und der Wert ein Schlüsselwort ist. Umgekehrt kannst du mit new CSSKeywordValue('none') selbst ein Objekt erzeugen und über attributeStyleMap.set() zuweisen. Der Vorteil gegenüber reinen Zeichenketten: Du kannst den Werttyp prüfen, etwa mit instanceof CSSKeywordValue, und musst keine Strings zerlegen. So lassen sich z. B. auto und eine konkrete Länge (CSSUnitValue) sauber auseinanderhalten.

Die einzige eigene Eigenschaft ist value. Sie enthält das Schlüsselwort als Zeichenkette und ist beschreibbar. toString() (geerbt von CSSStyleValue) gibt das Schlüsselwort so zurück, wie es in CSS geschrieben wird.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	string		Parameter des Konstruktors `new CSSKeywordValue(value)`: das Schlüsselwort bzw. der Bezeichner, z. B. `'auto'`. Eine leere Zeichenkette löst einen `TypeError` aus.
$CSSKeywordValue.value	string		Eigenschaft (lesen und schreiben): der Bezeichner des Schlüsselworts. Auch beim Setzen einer leeren Zeichenkette gibt es einen `TypeError`.

Rückgabewert

Typ

CSSKeywordValue

Beschreibung

Der Konstruktor gibt ein neues CSSKeywordValue-Objekt zurück. Du kannst es an StylePropertyMap.set() übergeben oder mit toString() in eine Zeichenkette umwandeln.

Beispiele

Objekt erzeugen und einem Element zuweisen

const box = document.querySelector('.box');

// Schlüsselwort als typisiertes Objekt erzeugen
const hidden = new CSSKeywordValue('none');
console.log(hidden.value);      // 'none'
console.log(String(hidden));    // 'none'

// Wie box.style.display = 'none', nur typisiert
box.attributeStyleMap.set('display', hidden);
console.log(box.style.display);

none none none

Berechneten Wert auslesen und Typ prüfen

const el = document.querySelector('main');
const width = el.computedStyleMap().get('width');

if (width instanceof CSSKeywordValue) {
  console.log(`Schlüsselwort: ${width.value}`);
} else if (width instanceof CSSUnitValue) {
  console.log(`Länge: ${width.value}${width.unit}`);
}

const display = el.computedStyleMap().get('display');
console.log(display.constructor.name, display.value);

Länge: 960px CSSKeywordValue block

Wert parsen und nachträglich ändern

const parsed = CSSStyleValue.parse('justify-content', 'center');
console.log(parsed instanceof CSSKeywordValue); // true

parsed.value = 'space-between';
document.querySelector('nav').attributeStyleMap.set('justify-content', parsed);

try {
  new CSSKeywordValue('');
} catch (err) {
  console.log(err.name); // TypeError
}

true TypeError

Funktionsunterstützung prüfen und Ersatzweg nutzen

const setDisplay = (el, keyword) => {
  if ('CSSKeywordValue' in window && el.attributeStyleMap) {
    el.attributeStyleMap.set('display', new CSSKeywordValue(keyword));
  } else {
    el.style.display = keyword; // Ersatz, z. B. für Firefox
  }
};

setDisplay(document.body, 'grid');

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome, Edge und Opera unterstützen die Schnittstelle ab Version 66 bzw. 79, Safari ab 16.4. Firefox unterstützt das CSS Typed OM nicht. Prüfe die Unterstützung deshalb vorab mit 'CSSKeywordValue' in window und sieh einen Ersatzweg über element.style vor.
Der Konstruktor prüft nicht, ob das Schlüsselwort zur Eigenschaft passt. new CSSKeywordValue('banana') funktioniert. Erst attributeStyleMap.set('display', …) löst bei einem ungültigen Wert einen TypeError aus.
Eine leere Zeichenkette als value löst sofort einen TypeError aus, sowohl im Konstruktor als auch beim Setzen der Eigenschaft.
Werte in Anführungszeichen (z. B. content: "abc") und benutzerdefinierte Eigenschaften (--foo) sind keine CSSKeywordValue-Objekte. Du bekommst dafür meist ein CSSUnparsedValue oder ein allgemeines CSSStyleValue.
Groß- und Kleinschreibung bleibt in value so erhalten, wie du sie angibst. Vergleiche deshalb am besten mit kleingeschriebenen Schlüsselwörtern.

Siehe auch

CSSStyleValue CSSUnitValue CSSNumericValue CSSUnparsedValue StylePropertyMap Element.computedStyleMap() HTMLElement.attributeStyleMap