CSSMathClamp — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSMathClamp extends CSSMathValue

Beschreibung

CSSMathClamp gehört zur CSS Typed Object Model API (Houdini) und bildet die CSS-Funktion clamp() als typisiertes JavaScript-Objekt ab. Statt Zeichenketten wie "clamp(16px, 4vw, 32px)" selbst zusammenzubauen oder mit regulären Ausdrücken zu zerlegen, arbeitest du mit einem Objekt, das Minimum, bevorzugten Wert und Maximum getrennt als CSSNumericValue enthält.

Die Schnittstelle erbt von CSSMathValue und damit von CSSNumericValue und CSSStyleValue. Deshalb stehen Methoden wie add(), mul(), to(), type() und toString() zur Verfügung. Die Eigenschaft operator hat bei dieser Schnittstelle immer den Wert "clamp".

lower: die untere Grenze (CSSNumericValue, schreibgeschützt)
value: der bevorzugte Wert (CSSNumericValue, schreibgeschützt)
upper: die obere Grenze (CSSNumericValue, schreibgeschützt)

Die Schnittstelle ist nützlich für flüssige Typografie oder responsive Abstände, die per Skript erzeugt oder ausgewertet werden, etwa in Design-Token-Werkzeugen, Editoren oder Animations-Bibliotheken. Die fertigen Objekte kannst du direkt an element.attributeStyleMap.set() übergeben.

Parameter

Name	Typ	Beschreibung
$lower Pflicht	CSSNumericValue\|number	Konstruktor-Argument: die untere Grenze (Minimum) von `clamp()`, z. B. `CSS.px(16)`. Eine reine Zahl wird als `CSSUnitValue` mit der Einheit `number` behandelt.
$value Pflicht	CSSNumericValue\|number	Konstruktor-Argument: der bevorzugte Wert, z. B. `CSS.vw(4)`. Er muss zum Typ von `lower` und `upper` passen.
$upper Pflicht	CSSNumericValue\|number	Konstruktor-Argument: die obere Grenze (Maximum) von `clamp()`, z. B. `CSS.px(32)`.

Beispiele

Instanz erzeugen und Eigenschaften auslesen

// Funktionsprüfung, bevor die API genutzt wird
if ('CSSMathClamp' in window) {
  const fontSize = new CSSMathClamp(CSS.px(16), CSS.vw(4), CSS.px(32));

  console.log(fontSize.operator);          // "clamp"
  console.log(fontSize.lower.toString());  // "16px"
  console.log(fontSize.value.toString());  // "4vw"
  console.log(fontSize.upper.toString());  // "32px"
  console.log(fontSize.toString());
}

clamp 16px 4vw 32px clamp(16px, 4vw, 32px)

Flüssige Schriftgröße per attributeStyleMap setzen

const heading = document.querySelector('h1');

// Minimum 1.5rem, bevorzugt 1rem + 3vw, Maximum 3rem
const fluid = new CSSMathClamp(
  CSS.rem(1.5),
  new CSSMathSum(CSS.rem(1), CSS.vw(3)),
  CSS.rem(3)
);

heading.attributeStyleMap.set('font-size', fluid);

console.log(heading.style.fontSize);

clamp(1.5rem, 1rem + 3vw, 3rem)

Vorhandenen clamp()-Wert erkennen und die Grenzen anpassen

const box = document.querySelector('.card');
box.style.width = 'clamp(200px, 50%, 600px)';

const width = box.attributeStyleMap.get('width');

if (width instanceof CSSMathClamp) {
  // Die Eigenschaften sind schreibgeschützt, deshalb ein neues Objekt bauen
  const wider = new CSSMathClamp(width.lower, width.value, CSS.px(800));
  box.attributeStyleMap.set('width', wider);
  console.log(box.style.width);
}

clamp(200px, 50%, 800px)

Inkompatible Typen führen zu einem TypeError

try {
  // Länge und Zeit lassen sich nicht vergleichen
  new CSSMathClamp(CSS.px(10), CSS.s(1), CSS.px(20));
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: CSSMathClamp gibt es derzeit nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox unterstützt das CSS Typed OM überhaupt nicht, Safari unterstützt zwar Teile des Typed OM, aber CSSMathClamp nicht. Prüfe die Unterstützung vorher mit 'CSSMathClamp' in window und greife sonst auf element.style.setProperty('font-size', 'clamp(…)') zurück.

Typprüfung: Alle drei Argumente müssen kompatible CSS-Typen haben (z. B. alle Längen oder Länge/Prozent). Sonst wirft der Konstruktor einen TypeError.
Schreibgeschützt: lower, value und upper lassen sich nicht nachträglich ändern. Für Änderungen erzeugst du eine neue Instanz.
Keine Prüfung der Grenzen: Liegt lower über upper, meldet der Konstruktor keinen Fehler. Wie in CSS gewinnt dann beim Berechnen die untere Grenze.
Berechnete Werte: element.computedStyleMap().get() gibt normalerweise den bereits aufgelösten Wert zurück (etwa CSSUnitValue in px), kein CSSMathClamp-Objekt. Ein CSSMathClamp bekommst du vor allem aus attributeStyleMap bzw. aus Stilregeln mit angegebenen Werten.

Siehe auch

CSSMathMax CSSMathSum CSSMathMin CSSMathNegate CSSMathValue