CSSScale.x — Eigenschaft · JavaScript-Referenz

Signatur

CSSScale.x

Beschreibung

Die Eigenschaft x des CSSScale-Interfaces gehört zur CSS Typed Object Model API (Houdini). Sie steht für den horizontalen Skalierungsfaktor einer scale()-, scaleX()- oder scale3d()-Transformation. Ein Wert von 1 lässt die Breite unverändert, 2 verdoppelt sie, 0.5 halbiert sie. Negative Werte spiegeln das Element horizontal.

Beim Lesen bekommst du immer ein CSSNumericValue zurück, meist ein CSSUnitValue mit der Einheit "number". Den reinen Zahlenwert erhältst du über .value. Beim Schreiben kannst du eine einfache Zahl (CSSNumberish) oder ein CSSNumericValue übergeben, etwa CSS.number(1.5) oder einen CSSMathSum, der sich zu einer einheitenlosen Zahl auflöst.

Nützlich ist x, wenn du Transformationen per JavaScript gezielt änderst, zum Beispiel in Animationen oder bei Zoom-Effekten, die an Mausrad oder Gesten gekoppelt sind. Du musst dann keine transform-Zeichenketten zusammensetzen und wieder auseinandernehmen. Wichtig: Eine Änderung an x wirkt sich erst auf das Element aus, wenn du die CSSTransformValue erneut über attributeStyleMap.set() zuweist.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number \| CSSNumericValue		Neuer Skalierungsfaktor für die x-Achse (nur beim Setzen). Muss sich zum Typ `<number>` auflösen, also ohne Einheit sein.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Der horizontale Skalierungsfaktor, meist als CSSUnitValue mit unit === "number".

Beispiele

Skalierungsfaktor auslesen

const scale = new CSSScale(2, 0.5);

console.log(scale.x.value);   // Zahlenwert
console.log(scale.x.unit);    // Einheit
console.log(scale.toString());

2 number scale(2, 0.5)

x-Faktor ändern und auf ein Element anwenden

const box = document.querySelector('.box');
const scale = new CSSScale(1, 1);

// Nur horizontal strecken
scale.x = CSS.number(1.5);

box.attributeStyleMap.set('transform', new CSSTransformValue([scale]));
console.log(box.style.transform);

scale(1.5, 1)

Horizontaler Zoom per Mausrad

const img = document.querySelector('img');
img.style.transform = 'scale(1, 1)';

img.addEventListener('wheel', (event) => {
  event.preventDefault();
  const transform = img.attributeStyleMap.get('transform');
  const scale = transform[0]; // CSSScale

  const next = Math.min(4, Math.max(0.25, scale.x.value - event.deltaY * 0.001));
  scale.x = next; // einfache Zahl ist erlaubt

  img.attributeStyleMap.set('transform', transform);
}, { passive: false });

Ungültige Einheit führt zu TypeError

const scale = new CSSScale(1, 1);

try {
  scale.x = CSS.px(10); // Länge statt Zahl
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Nur einheitenlose Werte: Wenn du einen Wert mit Einheit zuweist, etwa CSS.px(10) oder CSS.percent(50), wird ein TypeError ausgelöst. Prozentangaben wie in scale(150%) werden beim Parsen zu Zahlen umgerechnet.
Keine automatische Aktualisierung: CSSScale-Objekte sind nicht direkt mit dem Element verbunden. Nach einer Änderung musst du die CSSTransformValue erneut mit attributeStyleMap.set() zuweisen.
Lesen immer als Objekt: Auch wenn du eine Zahl zugewiesen hast, liefert der Getter ein CSSUnitValue zurück. Den Zahlenwert erhältst du mit .value.
Berechnete Stile: computedStyleMap().get('transform') liefert je nach Browser eine aufgelöste Matrix (CSSMatrixComponent) statt eines CSSScale. Frag vorher mit instanceof CSSScale ab, welchen Typ du bekommen hast.
Kompatibilität: Das CSS Typed OM wird von Chromium-Browsern (Chrome, Edge, Opera) und von Safari ab 16.4 unterstützt, von Firefox bisher nicht. Prüfe die Unterstützung vorab, z. B. mit 'CSSScale' in window, und verwende sonst element.style.transform als Ausweichlösung.

Siehe auch

CSSScale.y CSSScale.z CSSRotate.x CSSRotate.y CSSRotate.z