CSSNumericArray — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSNumericArray

Beschreibung

CSSNumericArray gehört zur CSS Typed Object Model API (Typed OM). Die Schnittstelle speichert die Operanden eines mathematischen CSS-Ausdrucks als typisierte Objekte. Man muss diese Werte also nicht mühsam aus Zeichenketten wie "calc(100% - 20px)" herauslesen, sondern greift direkt auf echte CSSUnitValue- oder verschachtelte CSSMathValue-Objekte zu.

Man erzeugt ein CSSNumericArray nie selbst, denn es gibt keinen öffentlichen Konstruktor. Man bekommt es über die Eigenschaft values dieser Klassen:

CSSMathSum (entspricht calc(a + b))
CSSMathProduct (entspricht calc(a * b))
CSSMathMin (entspricht min(a, b))
CSSMathMax (entspricht max(a, b))

Die wichtigsten Bestandteile der Schnittstelle:

length: Anzahl der enthaltenen Werte (nur lesbar).
Indexzugriff array[i]: liefert den CSSNumericValue an Position i.
Iteration: for...of, forEach(), entries(), keys(), values() sowie der Spread-Operator bzw. Array.from().

Das Objekt ist kein echtes Array. Methoden wie map() oder filter() gibt es nicht, und die Liste lässt sich nicht verändern. Wer eine Array-Methode braucht, wandelt die Liste vorher mit Array.from() oder [...values] um.

Beispiele

Operanden eines CSSMathSum auslesen

// Entspricht calc(10px + 50%)
const sum = new CSSMathSum(CSS.px(10), CSS.percent(50));
const values = sum.values; // CSSNumericArray

console.log(values.length);
console.log(values[0].toString());
console.log(values[1].value, values[1].unit);

2 10px 50 percent

calc()-Wert eines Elements mit for...of zerlegen

const box = document.createElement('div');
document.body.append(box);
box.attributeStyleMap.set('width', 'calc(100% - 20px)');

const width = box.attributeStyleMap.get('width'); // CSSMathSum
for (const operand of width.values) {
  console.log(operand.constructor.name, operand.toString());
}

CSSUnitValue 100% CSSMathNegate calc(-1 * 20px)

In ein echtes Array umwandeln und map() nutzen

// Entspricht min(200px, 50vw)
const clamp = new CSSMathMin(CSS.px(200), CSS.vw(50));

const units = Array.from(clamp.values, (v) => v.unit);
const texts = [...clamp.values].map((v) => v.toString());

console.log(units);
console.log(texts);

["px", "vw"] ["200px", "50vw"]

Mit forEach() und Index durchlaufen

const product = new CSSMathProduct(CSS.number(2), CSS.em(1.5));

product.values.forEach((value, index) => {
  console.log(`#${index}: ${value}`);
});

#0: 2 #1: 1.5em

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es bisher nicht. Prüfe die Unterstützung mit einer Feature-Erkennung wie if ('CSSMathSum' in window) und plane einen Fallback über Zeichenketten und getComputedStyle() ein.
Kein echtes Array: Array.isArray(sum.values) ergibt false. Methoden wie map(), filter() oder reduce() fehlen, dafür wird Array.from() benötigt.
Nur lesbar: Zuweisungen wie values[0] = CSS.px(5) werden stillschweigend ignoriert (im Strict Mode lösen sie einen TypeError aus). Wer andere Operanden will, erzeugt ein neues CSSMathSum usw.
Verschachtelung: Die Einträge können selbst wieder CSSMathValue-Objekte sein, etwa CSSMathNegate bei einer Subtraktion oder CSSMathInvert bei einer Division. Wer alle Werte auslesen will, muss die Struktur rekursiv durchlaufen.
Kein Konstruktor: new CSSNumericArray() löst einen TypeError aus.
Der Browser kann Ausdrücke vereinfachen, beim Lesen berechneter Werte über computedStyleMap() zum Beispiel. Die Zahl und Reihenfolge der Operanden kann deshalb vom geschriebenen CSS abweichen.

Siehe auch

CSSNumericValue CSSMediaRule CSSNamespaceRule PluginArray CSSFunctionRule