CSSPrimitiveValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSPrimitiveValue extends CSSValue

Beschreibung

CSSPrimitiveValue leitet sich von CSSValue ab und steht für einen einzelnen primitiven CSS-Wert, etwa 12px, 50%, 1.5em, url(bild.png) oder rgb(255, 0, 0). Man erhielt ein solches Objekt früher über CSSStyleDeclaration.getPropertyCSSValue(), meist auf dem Ergebnis von window.getComputedStyle().

Der Vorteil gegenüber reinen Strings war, dass Wert und Einheit getrennt vorlagen: Die Eigenschaft primitiveType liefert eine Einheiten-Konstante (z. B. CSS_PX = 5, CSS_PERCENTAGE = 2), und Methoden wie getFloatValue(unitType) konnten Werte sogar in andere absolute Einheiten umrechnen. Weitere Methoden:

getFloatValue(unitType) / setFloatValue(unitType, floatValue) – numerische Werte lesen bzw. setzen.
getStringValue() / setStringValue(stringType, stringValue) – für Strings, Bezeichner (CSS_IDENT), URLs und attr().
getCounterValue(), getRectValue(), getRGBColorValue() – liefern Counter-, Rect- bzw. RGBColor-Objekte.

Heute sollte man das Interface nicht mehr verwenden. Es wurde nie von allen Browsern vollständig umgesetzt und aus Chrome und Firefox entfernt. Der moderne Nachfolger ist das CSS Typed Object Model (CSSUnitValue, CSSStyleValue, element.computedStyleMap()). Für einfache Fälle reicht getComputedStyle() zusammen mit getPropertyValue() und parseFloat().

Parameter

Name	Typ	Beschreibung
$unitType Pflicht	number	Parameter von `getFloatValue()`/`setFloatValue()`: Einheiten-Konstante, z. B. `CSSPrimitiveValue.CSS_PX` (5), `CSS_PERCENTAGE` (2), `CSS_EMS` (3), `CSS_DEG` (11), `CSS_MS` (14).
$floatValue Pflicht	number	Parameter von `setFloatValue()`: der neue Zahlenwert in der angegebenen Einheit.
$stringType Pflicht	number	Parameter von `setStringValue()`: `CSS_STRING` (19), `CSS_URI` (20), `CSS_IDENT` (21) oder `CSS_ATTR` (22).
$stringValue Pflicht	string	Parameter von `setStringValue()`: der neue Zeichenkettenwert.

Rückgabewert

Typ

Beschreibung

Je nach Methode: getFloatValue() gibt eine number zurück, getStringValue() einen string, die übrigen Getter entsprechende Objekte. Die Setter geben nichts zurück (void) und werfen bei berechneten, schreibgeschützten Werten eine DOMException (NoModificationAllowedError).

Beispiele

Feature-Erkennung vor der Nutzung

// Prüfen, ob die veraltete API überhaupt verfügbar ist
const hasLegacyCSSOM =
  typeof window.CSSPrimitiveValue !== 'undefined' &&
  typeof CSSStyleDeclaration.prototype.getPropertyCSSValue === 'function';

console.log(hasLegacyCSSOM ? 'CSSPrimitiveValue verfügbar' : 'Nicht unterstützt – modernen Weg verwenden');

Nicht unterstützt – modernen Weg verwenden

Legacy-Zugriff auf einen berechneten Pixelwert (mit Absicherung)

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

if (typeof style.getPropertyCSSValue === 'function') {
  const value = style.getPropertyCSSValue('width'); // CSSPrimitiveValue
  if (value.primitiveType === CSSPrimitiveValue.CSS_PX) {
    console.log('Breite:', value.getFloatValue(CSSPrimitiveValue.CSS_PX));
  }
} else {
  // Fallback: String auswerten
  console.log('Breite:', parseFloat(style.getPropertyValue('width')));
}

Breite: 200

Moderner Ersatz: CSS Typed OM mit computedStyleMap()

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

if ('computedStyleMap' in Element.prototype) {
  const width = box.computedStyleMap().get('width'); // CSSUnitValue
  console.log(width.value, width.unit);

  // Umrechnen wie früher mit getFloatValue()
  const inInch = CSS.px(width.value).to('in');
  console.log(inInch.value.toFixed(2), inInch.unit);
}

200 px 2.08 in

// Wichtig · Fallstricke

Veraltet und entfernt: Chrome hat getPropertyCSSValue() und damit CSSPrimitiveValue schon früh entfernt, Firefox ab Version 62. Nur ältere WebKit-/Safari-Versionen boten es noch teilweise an. In neuem Code nicht verwenden.

Die Setter (setFloatValue(), setStringValue()) funktionieren bei Werten aus getComputedStyle() nicht, weil berechnete Werte schreibgeschützt sind. Sie werfen dann eine DOMException.
getFloatValue() konnte nur zwischen absoluten Einheiten umrechnen (z. B. px → cm). Bei relativen Einheiten wie em oder % wurde ein InvalidAccessError geworfen.
Für Kurzschreibweisen (z. B. margin) lieferte getPropertyCSSValue() oft null oder eine CSSValueList statt eines CSSPrimitiveValue.
Ersatz: element.computedStyleMap() bzw. element.attributeStyleMap (CSS Typed OM; in Chromium-Browsern und Safari 16.4+ verfügbar, in Firefox noch nicht). Überall funktioniert getComputedStyle(el).getPropertyValue().

Siehe auch

CSSPositionValue CSSImageValue CSSMathValue CSSNumericValue CSSStyleValue