CSSPrimitiveValue.getStringValue() — Methode · JavaScript-Referenz

Signatur

CSSPrimitiveValue.prototype.getStringValue()

Beschreibung

Die Methode getStringValue() gehört zum veralteten Interface CSSPrimitiveValue aus der Spezifikation DOM Level 2 Style. Sie liest den Inhalt eines einfachen CSS-Werts als Zeichenkette aus. Das funktioniert nur bei Werten, deren primitiveType einer dieser Konstanten entspricht:

CSS_STRING (19), z. B. der Inhalt von content: "Hallo"
CSS_URI (20), z. B. die URL aus url(bild.png)
CSS_IDENT (21), z. B. Schlüsselwörter wie block oder auto
CSS_ATTR (22), der Attributname aus attr(title)

An ein CSSPrimitiveValue-Objekt kam man früher über CSSStyleDeclaration.getPropertyCSSValue(), meist in Verbindung mit window.getComputedStyle(). Anders als die reine Textausgabe von cssText liefert getStringValue() den Wert ohne CSS-Syntax. Bei einer URL fehlen also url( und die Anführungszeichen.

Neuen Code sollte man nicht mehr damit schreiben. Nimm stattdessen getPropertyValue() (liefert einen String) oder die CSS Typed OM mit element.computedStyleMap() und CSSKeywordValue, CSSUnparsedValue und ähnlichen Klassen.

Rückgabewert

Typ

string

Beschreibung

Der Wert als Zeichenkette ohne CSS-Syntax, z. B. "bild.png" bei url(bild.png). Wenn der Wert kein String-Typ ist (z. B. CSS_PX), wird eine DOMException vom Typ InvalidAccessError ausgelöst.

Beispiele

Klassische Nutzung mit Funktionsprüfung

const el = document.body;
const style = getComputedStyle(el);

if (typeof style.getPropertyCSSValue === 'function') {
  const value = style.getPropertyCSSValue('display');
  // CSS_IDENT = 21
  if (value.primitiveType === 21) {
    console.log('display:', value.getStringValue());
  }
} else {
  console.log('Veraltete API nicht verfügbar – Rückfall:', style.getPropertyValue('display'));
}

Veraltete API nicht verfügbar – Rückfall: block

Hintergrundbild-URL auslesen: alt und modern

const box = document.createElement('div');
box.style.backgroundImage = 'url("https://example.com/bild.png")';
document.body.append(box);

const getBackgroundUrl = (el) => {
  const cs = getComputedStyle(el);
  // Alter Weg über CSSPrimitiveValue.getStringValue()
  if (typeof cs.getPropertyCSSValue === 'function') {
    return cs.getPropertyCSSValue('background-image').getStringValue();
  }
  // Moderner Weg: String auswerten
  const match = cs.getPropertyValue('background-image').match(/url\(["']?(.*?)["']?\)/);
  return match ? match[1] : null;
};

console.log(getBackgroundUrl(box));

https://example.com/bild.png

Fehler bei Werten, die keine Strings sind, abfangen

const safeGetString = (primitiveValue) => {
  try {
    return primitiveValue.getStringValue();
  } catch (err) {
    // InvalidAccessError, z. B. bei CSS_PX
    console.warn('Kein String-Wert:', err.name);
    return null;
  }
};

// Moderne Alternative mit der CSS Typed OM
const el = document.body;
if (el.computedStyleMap) {
  const display = el.computedStyleMap().get('display');
  console.log(display.constructor.name, display.value);
}

CSSKeywordValue block

// Wichtig · Fallstricke

Veraltet und entfernt: CSSPrimitiveValue, CSSValue und getPropertyCSSValue() sind nicht mehr Teil der aktuellen CSSOM-Spezifikation. Chrome und Safari haben sie schon vor Jahren entfernt. Firefox hat sie zuletzt nur noch eingeschränkt unterstützt und dann ebenfalls entfernt. In aktuellen Browsern gibt es die Methode also praktisch nicht mehr. Prüfe deshalb immer vorher, ob sie verfügbar ist.

Die Methode wirft InvalidAccessError, wenn primitiveType nicht CSS_STRING, CSS_URI, CSS_IDENT oder CSS_ATTR ist. Das heißt: Längen, Farben und Zahlen gehen hier nicht.
getPropertyCSSValue() gibt für Kurzschreibweisen wie margin oder background oft null zurück.
Alternativen sind CSSStyleDeclaration.getPropertyValue() und die CSS Typed OM (computedStyleMap(), attributeStyleMap). Die Typed OM ist in Chromium-Browsern und Safari verfügbar, in Firefox nur eingeschränkt.

Siehe auch

CSSPrimitiveValue.setStringValue() CSSPrimitiveValue.getRectValue() CSSPrimitiveValue.getFloatValue() CSSPrimitiveValue.getCounterValue() CSSPrimitiveValue.setFloatValue()