new CSSScale() — Methode · JavaScript-Referenz

Signatur

new CSSScale(x, y[, z])

Beschreibung

Der Konstruktor CSSScale() gehört zum CSS Typed Object Model (Teil von CSS Houdini). Er erzeugt ein Objekt für die Skalierungsfunktion innerhalb eines transform-Werts. Werden nur x und y übergeben, entspricht das Objekt scale(x, y) und is2D ist true. Mit dem dritten Argument z entsteht scale3d(x, y, z) und is2D ist false.

Ein CSSScale allein ist noch kein vollständiger CSS-Wert. Um ihn einem Element zuzuweisen, verpackst du ihn in ein CSSTransformValue, oft zusammen mit anderen Transformationen wie CSSTranslate oder CSSRotate. Diesen Wert setzt du dann über element.attributeStyleMap.set('transform', …). So musst du keine Strings zusammensetzen oder parsen. Das ist schneller und weniger fehleranfällig, gerade bei Animationen, die jeden Frame neu berechnet werden.

Die Eigenschaften x, y und z kannst du nachträglich ändern. Mit toMatrix() erhältst du die zugehörige DOMMatrix, mit toString() die CSS-Schreibweise.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number \| CSSNumericValue		Skalierungsfaktor entlang der x-Achse. Muss eine einheitenlose Zahl sein, z. B. `2` oder `CSS.number(2)`.
$y Pflicht	number \| CSSNumericValue		Skalierungsfaktor entlang der y-Achse, ebenfalls einheitenlos.
$z	number \| CSSNumericValue	1 (dann gilt is2D = true)	Optionaler Skalierungsfaktor entlang der z-Achse. Wird er angegeben, stellt das Objekt `scale3d()` dar und `is2D` ist `false`.

Rückgabewert

Typ

CSSScale

Beschreibung

Ein neues CSSScale-Objekt mit den Eigenschaften x, y, z und is2D.

Beispiele

2D- und 3D-Skalierung erzeugen

const flat = new CSSScale(2, 0.5);
console.log(flat.toString(), flat.is2D);

const deep = new CSSScale(1, 2, 3);
console.log(deep.toString(), deep.is2D);

scale(2, 0.5) true scale3d(1, 2, 3) false

Transform per attributeStyleMap setzen

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

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(0), CSS.px(-10)),
  new CSSScale(1.1, 1.1)
]);

card.attributeStyleMap.set('transform', transform);
console.log(card.style.transform);

translate(0px, -10px) scale(1.1, 1.1)

Pulsierende Animation ohne String-Verkettung

const btn = document.querySelector('#pulse');
const scale = new CSSScale(1, 1);
const value = new CSSTransformValue([scale]);

const tick = (t) => {
  const f = 1 + Math.sin(t / 300) * 0.05;
  scale.x = f;
  scale.y = f;
  btn.attributeStyleMap.set('transform', value);
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

Matrix auslesen und Feature-Erkennung

if ('CSSScale' in window) {
  const m = new CSSScale(CSS.number(3), 0.5).toMatrix();
  console.log(m.a, m.d, m.is2D);
} else {
  console.log('CSS Typed OM wird nicht unterstützt');
}

3 0.5 true

// Wichtig · Fallstricke

Nur einheitenlose Zahlen: Übergibst du Werte mit Einheit wie CSS.px(2) oder CSS.percent(50), wirft der Konstruktor einen TypeError. Prozentangaben wie scale(150%) musst du vorher in Faktoren umrechnen (1.5).
Ein Argument reicht nicht: Anders als in CSS (scale(2)) ist y Pflicht. new CSSScale(2) wirft einen TypeError, daher für gleichmäßige Skalierung new CSSScale(2, 2) schreiben.
Nicht mit der Eigenschaft scale verwechseln: CSSScale steht für die Funktion innerhalb von transform, nicht für die eigenständige CSS-Eigenschaft scale.
Kompatibilität: Chromium-Browser unterstützen das CSS Typed OM ab Version 66, Safari ab 16.4. Firefox unterstützt es bisher nicht. Prüfe die Unterstützung vorher mit 'CSSScale' in window und nutze sonst element.style.transform mit Strings.
Änderungen an x/y/z werden erst sichtbar, wenn du den CSSTransformValue erneut mit attributeStyleMap.set() zuweist.

Siehe auch

new CSSRotate() new CSSSkew() new CSSSkewX() new CSSSkewY() new CSSTranslate()