new CSSTranslate() — Methode · JavaScript-Referenz

Signatur

new CSSTranslate(x, y, z)

Beschreibung

Der Konstruktor CSSTranslate() gehört zum CSS Typed Object Model (Houdini). Er erzeugt eine typisierte Darstellung einer Verschiebung. Damit müssen Sie keine Strings wie "translate(10px, 20px)" mehr zusammensetzen. Ein CSSTranslate ist eine Unterklasse von CSSTransformComponent. Man verwendet ihn meist als Bestandteil eines CSSTransformValue, der anschließend über element.attributeStyleMap.set('transform', …) gesetzt wird.

Die Achsenwerte werden als CSSNumericValue übergeben, also zum Beispiel über die Fabrikfunktionen CSS.px(), CSS.percent(), CSS.em() oder über CSSMathSum für calc()-Ausdrücke. Geben Sie nur x und y an, entsteht eine 2D-Verschiebung (is2D === true) und die Ausgabe lautet translate(…). Mit dem dritten Argument z entsteht eine 3D-Verschiebung, die als translate3d(…) ausgegeben wird.

Typisierte Werte sind vor allem bei Animationen und häufigen Stil-Änderungen nützlich. Der Browser muss dann keine Strings parsen. Außerdem können Sie die Einzelwerte über die Eigenschaften x, y und z direkt lesen und ändern.

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)`, `CSS.percent(50)`).
$y Pflicht	CSSNumericValue		Verschiebung entlang der Y-Achse. Muss eine Länge oder ein Prozentwert sein.
$z	CSSNumericValue	CSS.px(0) (Objekt ist dann 2D)	Optionale Verschiebung entlang der Z-Achse. Muss eine Länge sein, Prozentwerte sind nicht erlaubt. Wird `z` angegeben, ist `is2D` gleich `false`.

Rückgabewert

Typ

CSSTranslate

Beschreibung

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

Beispiele

2D- und 3D-Verschiebung erzeugen

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

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

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

Transform eines Elements typisiert setzen

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)

Verschiebung animieren, ohne Strings zu bauen

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

const step = (time) => {
  // x direkt auf dem typisierten Objekt ändern
  translate.x = CSS.px(Math.sin(time / 500) * 100);
  box.attributeStyleMap.set('transform', transform);
  requestAnimationFrame(step);
};

requestAnimationFrame(step);

Ungültige Einheiten abfangen

try {
  // Prozentwert für z ist nicht erlaubt
  new CSSTranslate(CSS.px(0), CSS.px(0), CSS.percent(10));
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es bisher nicht. Prüfen Sie die Verfügbarkeit mit if ('CSSTranslate' in window) und setzen Sie sonst element.style.transform als String.
Nicht passende Typen lösen einen TypeError aus. Das gilt zum Beispiel für CSS.number(5), Winkel wie CSS.deg() und Prozentwerte bei z. Einfache Zahlen werden nicht automatisch zu px umgewandelt.
CSSTranslate steht für die Funktion translate() innerhalb von transform. Die eigenständige CSS-Eigenschaft translate gibt es ebenfalls, sie wird aber nicht über dieses Objekt abgebildet.
Wenn Sie nachträglich is2D = true setzen, bleibt der Wert von z erhalten, wird aber bei der Ausgabe und in toMatrix() nicht berücksichtigt.
toMatrix() löst bei relativen Einheiten (z. B. % oder em) einen TypeError aus, weil diese ohne Layout-Kontext nicht in eine Matrix umgerechnet werden können.

Siehe auch

CSSTranslate CSSTransformValue CSSTransformComponent CSSRotate CSSScale CSSNumericValue