CSSScale — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSScale extends CSSTransformComponent

Beschreibung

CSSScale gehört zur CSS Typed Object Model API (Houdini) und steht für eine einzelne Skalierungsfunktion innerhalb eines transform-Werts. Die Schnittstelle erbt von CSSTransformComponent und ist meist ein Element eines CSSTransformValue, also der typisierten Liste aller Transformationsfunktionen eines Elements.

Ein CSSScale-Objekt hat die Eigenschaften x, y und z. Sie enthalten die Skalierungsfaktoren als CSSNumericValue (typischerweise CSSUnitValue mit der Einheit number). Über die geerbte Eigenschaft is2D sieht man, ob das Objekt als scale() (2D) oder als scale3d() (3D) ausgegeben wird. Die geerbten Methoden toMatrix() und toString() liefern die zugehörige DOMMatrix bzw. die CSS-Schreibweise.

Gebraucht wird CSSScale vor allem dann, wenn Transformationen per JavaScript ohne String-Verkettung gebaut oder ausgewertet werden sollen, etwa bei Animationen, Zoom-Reglern oder Editoren. Statt el.style.transform = `scale(${f})` zu schreiben, setzt man ein typisiertes Objekt über element.attributeStyleMap.set(). Das vermeidet Fehler beim Parsen und macht Werte direkt veränderbar.

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 ist is2D = true)	Optionaler Skalierungsfaktor entlang der Z-Achse. Wird er angegeben, ist das Objekt eine `scale3d()`-Funktion und `is2D` ist `false`.

Rückgabewert

Typ

CSSScale

Beschreibung

Der Konstruktor new CSSScale(x, y, z) gibt ein neues CSSScale-Objekt mit den Eigenschaften x, y, z und is2D zurück.

Beispiele

Objekt erzeugen und serialisieren

// 2D-Skalierung
const s2d = new CSSScale(2, 0.5);
console.log(s2d.toString());
console.log(s2d.is2D);

// 3D-Skalierung mit z-Faktor
const s3d = new CSSScale(1.5, 1.5, 2);
console.log(s3d.toString());
console.log(s3d.is2D);
console.log(s3d.x.value, s3d.x.unit);

scale(2, 0.5) true scale3d(1.5, 1.5, 2) false 1.5 number

Transformation typisiert auf ein Element setzen

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

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(20), CSS.px(0)),
  new CSSScale(1.2, 1.2)
]);

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

translate(20px, 0px) scale(1.2, 1.2)

Zoom-Regler: vorhandenen Scale-Wert auslesen und ändern

const img = document.querySelector('#bild');
const slider = document.querySelector('#zoom');

img.attributeStyleMap.set('transform', new CSSTransformValue([new CSSScale(1, 1)]));

slider.addEventListener('input', () => {
  const value = img.attributeStyleMap.get('transform');
  // Die erste CSSScale-Komponente suchen
  const scale = [...value].find((c) => c instanceof CSSScale);
  if (scale) {
    const factor = Number(slider.value);
    scale.x = CSS.number(factor);
    scale.y = CSS.number(factor);
    img.attributeStyleMap.set('transform', value);
  }
});

Matrix aus einer Skalierung berechnen

const scale = new CSSScale(2, 3);
const m = scale.toMatrix();
console.log(m.a, m.d, m.is2D);

2 3 true

// Wichtig · Fallstricke

Browser-Unterstützung: Die CSS Typed OM wird in Chromium-Browsern (Chrome, Edge, Opera ab Version 66) und in Safari ab 16.4 unterstützt, in Firefox nicht. Prüfen Sie das vorher, z. B. mit if ('CSSScale' in window), und schreiben Sie sonst den String über element.style.transform.
Die Faktoren müssen einheitenlos sein. new CSSScale(CSS.px(2), 1) löst einen TypeError aus. Prozentwerte wie scale(150%) werden ebenfalls nicht als CSSUnitValue mit % akzeptiert.
CSSScale steht für die Funktion scale() innerhalb von transform, nicht für die eigenständige CSS-Eigenschaft scale. Die wird in der Typed OM derzeit oft nur als CSSStyleValue geliefert.
Wenn Sie x, y oder z ändern, passiert am Element nichts, solange Sie den CSSTransformValue nicht erneut mit attributeStyleMap.set() zuweisen.
Wenn Sie is2D auf true setzen, wird z beim Serialisieren und in toMatrix() ignoriert. Der Wert bleibt aber im Objekt gespeichert.

Siehe auch

CSSRule CSSValue CSSRotate CSSSkew CSSSkewX