CSSNumericValue.type() — Methode · JavaScript-Referenz

Signatur

CSSNumericValue.prototype.type()

Beschreibung

Mit type() stellst du fest, zu welcher Dimensionskategorie ein numerischer CSS-Wert aus dem CSS Typed OM gehört. Die Methode gibt keinen einfachen String zurück, sondern ein Objekt (CSSNumericType). Dessen Schlüssel sind die Basistypen length, angle, time, frequency, resolution, flex und percent, ihre Werte sind ganzzahlige Exponenten. Dazu kann noch percentHint kommen.

Ein einfacher Wert wie CSS.px(10) liefert { length: 1 }. Bei berechneten Werten (CSSMathProduct, CSSMathInvert usw.) werden die Exponenten kombiniert: 10px / 2s ergibt { length: 1, time: -1 }. Eine einheitenlose Zahl (CSS.number(5)) liefert ein leeres Objekt {}. Basistypen mit dem Exponenten 0 kommen im Ergebnis nicht vor.

Der Eintrag percentHint erscheint, wenn Prozentwerte mit einem anderen Typ verrechnet werden, z. B. in calc(10px + 5%). Er enthält dann den Namen des Basistyps, in den die Prozentangabe aufgelöst wird (hier "length").

Typische Anwendungsfälle sind Prüfungen vor Rechenoperationen, bei Animationen oder in CSS-Houdini-Worklets (Paint API, Layout API). So erkennst du, ob ein Wert eine Länge, ein Winkel oder eine Zeit ist, bevor du ihn z. B. mit to() umrechnest oder mit add() verrechnest.

Rückgabewert

Typ

CSSNumericType (Objekt)

Beschreibung

Ein Objekt mit den optionalen ganzzahligen Eigenschaften length, angle, time, frequency, resolution, flex und percent (jeweils der Exponent) sowie optional percentHint (String mit dem Namen eines Basistyps). Basistypen mit dem Exponenten 0 fehlen im Objekt.

Beispiele

Typ einfacher Werte bestimmen

// Einfache Einheitenwerte über die CSS-Fabrikmethoden
console.log(CSS.px(10).type());
console.log(CSS.deg(45).type());
console.log(CSS.ms(300).type());
console.log(CSS.percent(50).type());
console.log(CSS.fr(1).type());
console.log(CSS.number(5).type()); // einheitenlos

{ length: 1 } { angle: 1 } { time: 1 } { percent: 1 } { flex: 1 } {}

Zusammengesetzte Typen bei Berechnungen

// Geschwindigkeit: Länge pro Zeit
const speed = CSS.px(200).div(CSS.s(2));
console.log(speed.type());

// Fläche: Länge zum Quadrat
const area = CSS.px(10).mul(CSS.px(20));
console.log(area.type());

// Länge plus Prozent → percentHint
const mixed = CSS.px(10).add(CSS.percent(5));
console.log(mixed.toString(), mixed.type());

{ length: 1, time: -1 } { length: 2 } calc(10px + 5%) { length: 1, percentHint: "length" }

Eingabewert vor dem Setzen validieren

// Nur echte Längen dürfen als Breite gesetzt werden
const isLength = (value) => {
  const t = value.type();
  const keys = Object.keys(t).filter((k) => k !== 'percentHint');
  return keys.length === 1 && t.length === 1;
};

const box = document.querySelector('.box');
const input = CSSNumericValue.parse('12rem');

if (isLength(input)) {
  box.attributeStyleMap.set('width', input);
  console.log('Breite gesetzt:', box.attributeStyleMap.get('width').toString());
} else {
  console.warn('Kein Längenwert:', input.toString());
}

Breite gesetzt: 12rem

// Wichtig · Fallstricke

Kein String: Anders als der Name vermuten lässt, liefert type() ein Objekt. Ein Vergleich wie value.type() === 'length' ist deshalb immer false. Prüfe stattdessen value.type().length === 1.
Exponent 0 wird ausgelassen: Einheitenlose Zahlen liefern {}. Werte, deren Einheiten sich gegenseitig aufheben (z. B. 10px / 5px), ebenfalls.
Relative Einheiten: em, rem, vw usw. zählen alle als length. Der Typ verrät also nicht, ob sich ein Wert absolut umrechnen lässt. to('px') schlägt bei relativen Einheiten trotzdem fehl.
Browser-Kompatibilität: Das CSS Typed OM wird von Chromium-basierten Browsern (ab Version 66) und Safari (ab 16.4) unterstützt, von Firefox nicht. Prüfe vorab mit if ('CSSNumericValue' in window) und sieh eine Ausweichlösung über getComputedStyle() und String-Verarbeitung vor.

Siehe auch

CSSNumericValue.to() CSSNumericValue.add() CSSNumericValue.div() CSSNumericValue.max() CSSNumericValue.min()