CSSRotate.y — Eigenschaft · JavaScript-Referenz

Signatur

CSSRotate.y

Beschreibung

Die Eigenschaft y gehört zum Interface CSSRotate der CSS Typed OM. Zusammen mit x und z beschreibt sie den Vektor (x, y, z), um den ein Element gedreht wird. Ein CSSRotate entspricht damit der CSS-Funktion rotate3d(x, y, z, angle) bzw. bei einer reinen 2D-Drehung rotate(angle).

Beim Lesen gibt y einen CSSNumericValue zurück, typischerweise einen CSSUnitValue mit der Einheit "number". Beim Setzen akzeptiert die Eigenschaft einen CSSNumberish-Wert, also eine einfache Zahl oder einen einheitenlosen CSSNumericValue wie CSS.number(1).

Brauchbar ist y vor allem, wenn du 3D-Drehungen per Skript anpassen willst, ohne Transform-Strings zusammenzubauen und wieder zu zerlegen. Ein Beispiel wäre das Kippen einer Karte um die y-Achse abhängig von der Mausposition. Der Vektor muss nicht normiert sein. Nur seine Richtung zählt, (0, 2, 0) dreht also genauso wie (0, 1, 0).

Wird ein CSSRotate nur mit einem Winkel erzeugt (new CSSRotate(angle)), haben x und y den Wert 0, z ist 1 und is2D ist true.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number \| CSSNumericValue		Nur beim Setzen: neue y-Komponente des Achsenvektors. Der Wert muss einheitenlos sein (Typ `number`), sonst wird ein `TypeError` ausgelöst.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Die y-Komponente des Rotationsvektors, meist als CSSUnitValue mit unit: "number". Eine gesetzte einfache Zahl wird dabei in einen solchen Wert umgewandelt.

Beispiele

y-Komponente einer 3D-Rotation auslesen

// Drehung um 45° um die y-Achse
const rotation = new CSSRotate(0, 1, 0, CSS.deg(45));

console.log(rotation.y.value, rotation.y.unit);
console.log(rotation.is2D);
console.log(rotation.toString());

1 number false rotate3d(0, 1, 0, 45deg)

Standardwert bei einer 2D-Rotation

const flat = new CSSRotate(CSS.deg(30));

console.log(flat.x.value, flat.y.value, flat.z.value);
console.log(flat.is2D);
console.log(flat.toString());

0 0 1 true rotate(30deg)

Karte je nach Mausposition kippen

const card = document.querySelector('.card');
const rotation = new CSSRotate(0, 1, 0, CSS.deg(20));

card.addEventListener('pointermove', (event) => {
  const rect = card.getBoundingClientRect();
  // Relative Position: -0.5 bis 0.5
  const relX = (event.clientX - rect.left) / rect.width - 0.5;
  const relY = (event.clientY - rect.top) / rect.height - 0.5;

  // Achsenvektor anpassen (muss nicht normiert sein)
  rotation.x = -relY;
  rotation.y = relX;

  card.attributeStyleMap.set('transform', new CSSTransformValue([rotation]));
});

Ungültige Einheit beim Setzen abfangen

const rotation = new CSSRotate(0, 1, 0, CSS.deg(90));

try {
  rotation.y = CSS.px(10); // Längen sind nicht erlaubt
} catch (err) {
  console.log(err.name);
}

rotation.y = CSS.number(0.5); // gültig
console.log(rotation.y.toString());

TypeError 0.5

// Wichtig · Fallstricke

Browser-Unterstützung: Die CSS Typed OM gibt es in Chromium-Browsern (ab Chrome/Edge 66) und in Safari (ab 16.4). Firefox unterstützt sie bisher nicht. Prüfe die Unterstützung vorher, z. B. mit if ('CSSRotate' in window), und sieh bei Bedarf einen Rückfall über element.style.transform mit einem String vor.
Nur einheitenlose Werte: y nimmt ausschließlich Zahlen oder CSSNumericValue-Werte vom Typ number an. Werte wie CSS.px() oder CSS.deg() lösen einen TypeError aus.
is2D beachten: Wenn du y änderst, ändert sich is2D nicht automatisch. Steht is2D auf true, wird die Drehung weiterhin als rotate(angle) serialisiert und angewendet, der neue y-Wert hat dann keine Wirkung. Setze in diesem Fall rotation.is2D = false.
Nullvektor: Sind x, y und z alle 0, gibt es keine gültige Achse. Der Browser wendet dann keine Drehung an.
Die Änderung wird erst sichtbar, wenn du das CSSRotate-Objekt erneut per attributeStyleMap.set() zuweist. Das Objekt ist nicht live mit dem Element verbunden.

Siehe auch

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