CSSTranslate.x — Eigenschaft · JavaScript-Referenz

Signatur

CSSTranslate.x

Beschreibung

Die Eigenschaft x gehört zur Schnittstelle CSSTranslate aus dem CSS Typed Object Model (Houdini). Ein CSSTranslate-Objekt steht für die CSS-Funktionen translate(), translateX() oder translate3d() innerhalb eines transform-Werts. x gibt an, wie weit das Element horizontal verschoben wird.

Der Wert ist kein String wie "10px", sondern ein typisiertes CSSNumericValue-Objekt, z. B. ein CSSUnitValue (CSS.px(10)) oder ein CSSMathValue (calc()-Ausdruck). Deshalb kann man mit dem Wert rechnen, ohne Strings zu zerlegen. Das lohnt sich vor allem bei Animationen und interaktiven Oberflächen, in denen Transformationen oft neu berechnet werden.

Der zugewiesene Wert muss den CSS-Typ <length-percentage> haben, also eine Länge (px, em, rem …) oder eine Prozentangabe. Nach einer Änderung von x muss das umgebende CSSTransformValue erneut per attributeStyleMap.set() auf das Element geschrieben werden. Erst dann ändert sich die Darstellung.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen) Pflicht	CSSNumericValue		Neue x-Verschiebung. Der Wert muss vom Typ <length-percentage> sein, z. B. `CSS.px(40)`, `CSS.percent(50)` oder `CSS.px(10).add(CSS.percent(5))`.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Die aktuelle horizontale Verschiebung als typisierter numerischer Wert, meist ein CSSUnitValue mit value und unit oder bei calc() ein CSSMathValue.

Beispiele

CSSTranslate erzeugen und x lesen/ändern

const verschiebung = new CSSTranslate(CSS.px(10), CSS.px(20));

console.log(verschiebung.x.value, verschiebung.x.unit);

// x auf 50 % setzen
verschiebung.x = CSS.percent(50);
console.log(verschiebung.toString());

10 "px" translate(50%, 20px)

Element per Typed OM horizontal verschieben

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

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

box.addEventListener('click', () => {
  // x um 25px erhöhen, ohne Strings zu parsen
  translate.x = CSS.px(translate.x.value + 25);
  box.attributeStyleMap.set('transform', transform);
  console.log(box.attributeStyleMap.get('transform').toString());
});

translate(25px, 0px) // nach dem ersten Klick

Vorhandene Transformation auslesen

const el = document.querySelector('#slider');
el.style.transform = 'translate(120px, 0) rotate(10deg)';

const transform = el.attributeStyleMap.get('transform');
const teil = [...transform].find((t) => t instanceof CSSTranslate);

if (teil) {
  console.log(`Horizontal: ${teil.x}`);
}

Horizontal: 120px

Ungültiger Typ löst TypeError aus

const t = new CSSTranslate(CSS.px(0), CSS.px(0));

try {
  t.x = CSS.deg(45); // Winkel statt Länge
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Typprüfung: Werte, die keine <length-percentage> sind (z. B. CSS.deg() oder CSS.number()), lösen beim Setzen einen TypeError aus. Ein einfacher String wie "10px" wird ebenfalls nicht angenommen.
Keine automatische Übernahme: Wenn du x änderst, ändert sich nur das JavaScript-Objekt. Damit das Element neu dargestellt wird, musst du den CSSTransformValue wieder mit element.attributeStyleMap.set('transform', …) setzen.
Prozentangaben beziehen sich bei translate auf die Breite der eigenen Rahmenbox (border box) des Elements, nicht auf die des Elternelements.
Berechnete Werte: computedStyleMap() kann Transformationen je nach Browser anders aufgelöst liefern. Wenn du Werte bearbeiten willst, lies sie besser aus attributeStyleMap.
Kompatibilität: Das CSS Typed OM wird von Chromium-Browsern (Chrome, Edge, Opera) und Safari ab 16.4 unterstützt, von Firefox bisher nicht. Vorher mit if ('CSSTranslate' in window) prüfen und sonst auf element.style.transform mit Strings ausweichen.

Siehe auch

CSSTranslate.y CSSTranslate.z CSSRotate.x CSSRotate.y CSSRotate.z