CSSStyleValue.parseAll() — Methode · JavaScript-Referenz

Signatur

CSSStyleValue.parseAll(property, cssText)

Beschreibung

CSSStyleValue.parseAll() gehört zum CSS Typed Object Model (Houdini). Die Methode nimmt einen Eigenschaftsnamen und einen CSS-Wert als Zeichenkette entgegen, prüft den Wert gegen die Grammatik dieser Eigenschaft und gibt ein Array mit allen daraus erzeugten Werten zurück. Anders als die MDN-Kurzbeschreibung vermuten lässt, wird dabei nichts an einem Element gesetzt. Die Methode parst nur.

Richtig nützlich wird sie bei listenwertigen Eigenschaften wie transition-duration, animation-name, background-image oder will-change. Dort steht jedes kommagetrennte Element für einen eigenen Wert. Die Schwestermethode CSSStyleValue.parse() liefert nur den ersten Wert, parseAll() dagegen alle. Bei Eigenschaften mit nur einem Wert enthält das Array genau ein Element.

Das Ergebnis kannst du direkt mit StylePropertyMap.set() oder append() weiterverwenden, zum Beispiel über element.attributeStyleMap.set(prop, ...werte). So kommst du ohne Zeichenketten-Verkettung aus und kannst mit Zahlen und Einheiten rechnen (etwa über CSSUnitValue.value und .unit).

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft, gegen deren Grammatik geparst wird, z. B. `"transition-duration"` oder eine benutzerdefinierte Eigenschaft wie `"--abstand"`.
$cssText Pflicht	string		Der zu parsende CSS-Wert als Zeichenkette, z. B. `"1s, 200ms"`.

Rückgabewert

Typ

CSSStyleValue[]

Beschreibung

Ein Array von CSSStyleValue-Objekten bzw. Unterklassen wie CSSUnitValue, CSSKeywordValue, CSSTransformValue, CSSImageValue oder CSSUnparsedValue. Ist der Wert ungültig, wird ein TypeError geworfen.

Beispiele

Kommagetrennte Übergangsdauern parsen

const dauern = CSSStyleValue.parseAll('transition-duration', '1s, 200ms, 0.5s');

for (const d of dauern) {
  console.log(d.constructor.name, d.value, d.unit);
}
console.log(dauern.length);

CSSUnitValue 1 s CSSUnitValue 200 ms CSSUnitValue 0.5 s 3

Unterschied zu parse()

const text = 'fade-in, slide-up';

const erster = CSSStyleValue.parse('animation-name', text);
const alle = CSSStyleValue.parseAll('animation-name', text);

console.log(erster.toString());
console.log(alle.map(v => v.toString()));

fade-in ["fade-in", "slide-up"]

Geparste Werte auf ein Element anwenden

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

// Dauern parsen, verdoppeln und typisiert setzen
const dauern = CSSStyleValue.parseAll('transition-duration', '150ms, 300ms')
  .map(d => CSS.ms(d.to('ms').value * 2));

box.attributeStyleMap.set('transition-duration', ...dauern);
console.log(box.style.transitionDuration);

300ms, 600ms

Eingaben sicher validieren

const istGueltig = (prop, wert) => {
  try {
    CSSStyleValue.parseAll(prop, wert);
    return true;
  } catch (err) {
    if (err instanceof TypeError) return false;
    throw err;
  }
};

console.log(istGueltig('transition-duration', '1s, 2s'));
console.log(istGueltig('transition-duration', 'rot'));
console.log(istGueltig('gibt-es-nicht', '1px'));

true false false

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser ab Version 66 und Safari ab 16.4 unterstützen die Methode. Firefox unterstützt das CSS Typed OM bisher nicht. Prüfe deshalb vorher mit if ('CSSStyleValue' in window && CSSStyleValue.parseAll), ob sie vorhanden ist.
Unbekannte Eigenschaften oder Werte, die nicht zur Grammatik passen, lösen einen TypeError aus. Es wird kein leeres Array zurückgegeben. Umschließe den Aufruf daher mit try/catch.
Die Methode ist statisch. Du rufst sie also über CSSStyleValue.parseAll() auf, nicht über eine Instanz. Den Konstruktor new CSSStyleValue() gibt es nicht: Er wirft einen Fehler.
Benutzerdefinierte Eigenschaften (--name) ohne Registrierung über CSS.registerProperty() ergeben ein CSSUnparsedValue. Dabei wird nichts nach Kommas aufgeteilt.
Kurzschreibweisen wie transition oder background liefern je nach Browser oft nur ein allgemeines CSSStyleValue, das nicht weiter aufgeschlüsselt ist. Verlässlich typisierte Ergebnisse bekommst du mit den Einzeleigenschaften (Langform).
var()-Ausdrücke im Wert werden nicht aufgelöst. Das Ergebnis ist dann ein CSSUnparsedValue.

Siehe auch

CSSStyleValue.parse() CSSStyleValue.toString() CSSNumericValue.parse() CSSStyleSheet.addRule() CSSStyleSheet.replace()