CSSTranslate — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSTranslate extends CSSTransformComponent

Beschreibung

CSSTranslate gehört zur CSS Typed Object Model API (Houdini). Das Interface steht für eine einzelne Verschiebung (translate() oder translate3d()) innerhalb eines transform-Werts. Es erbt von CSSTransformComponent und wird meist als Element eines CSSTransformValue verwendet, der die ganze Liste der Transformationsfunktionen abbildet.

Statt Zeichenketten wie "translate(" + x + "px, 0)" zusammenzubauen, arbeitest du mit echten numerischen Objekten (CSSUnitValue, CSSMathSum usw.). Das ist weniger fehleranfällig, erspart dem Browser das Parsen von Strings und eignet sich deshalb gut für Animationen per requestAnimationFrame oder für Houdini-Worklets.

Wichtige Mitglieder:

new CSSTranslate(x, y[, z]) – Konstruktor; x und y müssen Längen oder Prozentwerte sein, z muss eine Länge sein.
x, y, z – lesbare und schreibbare CSSNumericValue-Eigenschaften für die Verschiebung je Achse.
is2D (geerbt) – true, wenn kein z übergeben wurde. Dann serialisiert das Objekt als translate(), sonst als translate3d().
toMatrix() (geerbt) – liefert eine entsprechende DOMMatrix.
toString() (geerbt) – liefert die CSS-Schreibweise, z. B. "translate(10px, 50%)".

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	CSSNumericValue		Verschiebung entlang der X-Achse. Muss eine Länge oder ein Prozentwert sein, z. B. `CSS.px(10)` oder `CSS.percent(50)`.
$y Pflicht	CSSNumericValue		Verschiebung entlang der Y-Achse. Muss eine Länge oder ein Prozentwert sein.
$z	CSSNumericValue	CSS.px(0) (dann is2D = true)	Optionale Verschiebung entlang der Z-Achse. Muss eine Länge sein, Prozentwerte sind nicht erlaubt. Wenn du `z` angibst, wird `is2D` auf `false` gesetzt.

Rückgabewert

Typ

CSSTranslate

Beschreibung

Ein neues CSSTranslate-Objekt. Du kannst es in einen CSSTransformValue einfügen und über attributeStyleMap einem Element zuweisen.

Beispiele

Instanz erzeugen und serialisieren

const t2d = new CSSTranslate(CSS.px(10), CSS.percent(50));
console.log(t2d.toString(), t2d.is2D);

const t3d = new CSSTranslate(CSS.px(10), CSS.px(20), CSS.px(30));
console.log(t3d.toString(), t3d.is2D);

// Achsenwerte auslesen
console.log(t3d.z.value, t3d.z.unit);

translate(10px, 50%) true translate3d(10px, 20px, 30px) false 30 px

Transformation typisiert auf ein Element anwenden

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

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(100), CSS.px(0)),
  new CSSRotate(CSS.deg(45))
]);

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

translate(100px, 0px) rotate(45deg)

Performante Animation ohne String-Bau

const el = document.querySelector('.ball');
const move = new CSSTranslate(CSS.px(0), CSS.px(0));
const transform = new CSSTransformValue([move]);

const start = performance.now();
const tick = (now) => {
  const t = (now - start) / 1000;
  // Werte direkt am typisierten Objekt ändern
  move.x = CSS.px(Math.sin(t) * 150);
  move.y = CSS.px(Math.cos(t) * 50);
  el.attributeStyleMap.set('transform', transform);
  if (t < 5) requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

In eine DOMMatrix umwandeln

const t = new CSSTranslate(CSS.px(10), CSS.px(20));
const m = t.toMatrix();
console.log(m.e, m.f, m.is2D);

// Prozentwerte lassen sich nicht in eine Matrix umrechnen
try {
  new CSSTranslate(CSS.percent(50), CSS.px(0)).toMatrix();
} catch (err) {
  console.log(err.name);
}

10 20 true TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome, Edge, Opera) und ab Safari 16.4, in Firefox dagegen nicht. Prüfe vorher mit if ('CSSTranslate' in window) und halte eine Ausweichlösung über element.style.transform bereit.
TypeError bei falschen Einheiten: Der Konstruktor und die Setter werfen einen TypeError, wenn x oder y keine Länge bzw. kein Prozentwert ist (z. B. CSS.deg(10) oder CSS.number(5)) oder wenn z keine reine Länge ist. Prozentwerte sind für z ausdrücklich verboten.
toMatrix(): Die Methode funktioniert nur, wenn sich alle Werte in px umrechnen lassen. Bei %, em, vw oder calc() mit relativen Anteilen wird ein TypeError geworfen, weil das Objekt den Layout-Kontext nicht kennt.
Änderungen werden nicht automatisch übernommen: Wenn du x/y an einem Objekt änderst, wirkt sich das erst aus, wenn du den Wert erneut mit attributeStyleMap.set() zuweist.
Wird is2D nachträglich auf true gesetzt, bleibt z erhalten. Der Wert wird dann aber bei der Serialisierung und in toMatrix() ignoriert.

Siehe auch

CSSRotate CSSTransition Translator CSSMathNegate CSSRule