CSSTranslate.z — Eigenschaft · JavaScript-Referenz

Signatur

CSSTranslate.z

Beschreibung

Die Eigenschaft z eines CSSTranslate-Objekts steht für die Verschiebung entlang der z-Achse, also zum Betrachter hin oder von ihm weg. Sie gehört zum CSS Typed Object Model (Houdini). Damit lassen sich Transformationen als typisierte Objekte bearbeiten und nicht als Zeichenketten wie "translate3d(0, 0, 50px)".

Der Wert ist ein CSSNumericValue, meist ein CSSUnitValue wie CSS.px(50). Die z-Komponente muss eine Länge sein. Prozentwerte sind nicht erlaubt, weil ein Element keine Tiefe hat, auf die sich ein Prozentwert beziehen könnte. Wenn man den Konstruktor new CSSTranslate(x, y) ohne dritten Parameter aufruft, wird z auf CSS.px(0) gesetzt und is2D ist true.

Wichtig ist, wie z und is2D zusammenhängen: Solange is2D den Wert true hat, wird z bei der Serialisierung ignoriert und als translate(x, y) ausgegeben. Erst mit is2D = false entsteht translate3d(x, y, z). Die Eigenschaft wird typischerweise in Animationen, 3D-Effekten mit perspective oder beim Auslesen berechneter Transformationen über computedStyleMap() verwendet.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter) Pflicht	CSSNumericValue		Neuer Wert für die z-Komponente. Er muss sich als `<length>` auswerten lassen, zum Beispiel `CSS.px(20)`, `CSS.em(1)` oder `new CSSMathSum(CSS.px(10), CSS.rem(1))`.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Die aktuelle z-Komponente des Verschiebungsvektors, meist ein CSSUnitValue mit Längeneinheit. Beim Konstruktor ohne z-Argument ist der Standardwert CSS.px(0).

Beispiele

3D-Verschiebung erzeugen und z auslesen

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

console.log(move.z.value, move.z.unit);
console.log(move.is2D);
console.log(move.toString());

30 "px" false translate3d(10px, 20px, 30px)

z-Wert ändern und auf ein Element anwenden

const card = document.querySelector('.card');
const translate = new CSSTranslate(CSS.px(0), CSS.px(0));

// Ohne is2D = false würde z bei der Ausgabe ignoriert
translate.z = CSS.px(80);
translate.is2D = false;

card.attributeStyleMap.set('transform', new CSSTransformValue([translate]));
console.log(card.attributeStyleMap.get('transform').toString());

translate3d(0px, 0px, 80px)

z aus der berechneten Transformation lesen

const box = document.querySelector('#box');
box.style.transform = 'translateZ(2em) rotate(10deg)';

const transform = box.attributeStyleMap.get('transform');
for (const part of transform) {
  if (part instanceof CSSTranslate) {
    console.log('Tiefe:', part.z.toString());
  }
}

Tiefe: 2em

Ungültige Werte abfangen

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

try {
  t.z = CSS.percent(50); // Prozent ist für z nicht erlaubt
} catch (err) {
  console.log(err.name);
}
console.log(t.z.toString());

TypeError 0px

// Wichtig · Fallstricke

Fallstrick is2D: Wenn man z setzt, wird is2D nicht automatisch auf false gestellt. Solange is2D true ist, erscheint z nicht in toString(), und auch toMatrix() berücksichtigt den Wert nicht.
Nur Längen: Prozentwerte und einheitenlose Zahlen wie CSS.number(5) führen zu einem TypeError. Der bisherige Wert bleibt dabei erhalten.
Eine sichtbare Tiefenwirkung entsteht erst, wenn ein Elternelement eine perspective hat oder die Transformation eine perspective()-Funktion enthält.
Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern (ab Version 66) und in Safari (ab 16.4). Firefox unterstützt die API nicht. Vor der Nutzung sollte man die Unterstützung prüfen, etwa mit if ('CSSTranslate' in window), und sonst auf element.style.transform mit Zeichenketten ausweichen.
computedStyleMap().get('transform') liefert berechnete Werte oft als CSSMatrixComponent und nicht als CSSTranslate. In dem Fall gibt es kein z direkt, und der Wert muss aus der Matrix gelesen werden (m43).

Siehe auch

CSSTranslate CSSTranslate.x CSSTranslate.y CSSTransformComponent.is2D CSSTransformValue CSSNumericValue Element.computedStyleMap()