new CSSPerspective() — Methode · JavaScript-Referenz

Signatur

new CSSPerspective(length)

Beschreibung

Der Konstruktor CSSPerspective() gehört zum CSS Typed Object Model (Houdini). Er erzeugt eine Transformationskomponente (CSSTransformComponent), die der CSS-Funktion perspective() innerhalb der Eigenschaft transform entspricht. Damit legen Sie den Abstand zwischen Betrachter und der Ebene z = 0 fest. Nur mit ihm erhalten 3D-Transformationen wie rotateY() eine sichtbare Tiefenwirkung.

Sie verwenden ihn, wenn Sie Transformationen mit echten Objekten statt mit zusammengesetzten Zeichenketten aufbauen wollen. Mehrere Komponenten werden in einem CSSTransformValue zusammengefasst und über element.attributeStyleMap.set('transform', …) gesetzt. Das ist typsicher und spart das Parsen von Zeichenketten, zum Beispiel bei Animationen, die Sie per JavaScript steuern.

Der übergebene Wert muss eine Länge sein, etwa CSS.px(800) oder CSS.em(40). Neuere Implementierungen akzeptieren nach der aktuellen Spezifikation zusätzlich das Schlüsselwort 'none'. Die Eigenschaft is2D einer CSSPerspective ist immer false, weil eine Perspektive per Definition eine 3D-Operation ist.

Parameter

Name	Typ	Default	Beschreibung
$length Pflicht	CSSNumericValue \| CSSKeywordValue \| string		Abstand des Betrachters zur Ebene `z = 0`. Muss eine Länge sein, z. B. `CSS.px(500)`. Je nach Browser ist auch das Schlüsselwort `'none'` erlaubt.

Rückgabewert

Typ

CSSPerspective

Beschreibung

Ein neues CSSPerspective-Objekt mit den Eigenschaften length und is2D (immer false) sowie den geerbten Methoden toMatrix() und toString().

Beispiele

Einfache Instanziierung

const perspective = new CSSPerspective(CSS.px(500));

console.log(perspective.length.value, perspective.length.unit);
console.log(perspective.is2D);
console.log(perspective.toString());

500 'px' false perspective(500px)

3D-Drehung einer Karte mit Tiefenwirkung

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

const transform = new CSSTransformValue([
  new CSSPerspective(CSS.px(800)),
  new CSSRotate(0, 1, 0, CSS.deg(45))
]);

card.attributeStyleMap.set('transform', transform);
console.log(card.attributeStyleMap.get('transform').toString());

perspective(800px) rotate3d(0, 1, 0, 45deg)

Perspektive nachträglich ändern und Fehler abfangen

const p = new CSSPerspective(CSS.px(300));
p.length = CSS.px(1200); // Abstand vergrößern: schwächerer 3D-Effekt
console.log(p.toString());

try {
  new CSSPerspective(CSS.deg(90)); // Winkel ist keine Länge
} catch (err) {
  console.log(err.name);
}

perspective(1200px) TypeError

Feature-Erkennung mit Fallback

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

if ('CSSPerspective' in window && el.attributeStyleMap) {
  el.attributeStyleMap.set('transform', new CSSTransformValue([
    new CSSPerspective(CSS.px(600)),
    new CSSRotate(1, 0, 0, CSS.deg(30))
  ]));
} else {
  el.style.transform = 'perspective(600px) rotateX(30deg)';
}

// Wichtig · Fallstricke

Browserunterstützung: Das CSS Typed OM ist in Chromium-Browsern (Chrome, Edge, Opera) und Safari ab 16.4 verfügbar, in Firefox bisher nicht. Prüfen Sie die Unterstützung vorher, zum Beispiel mit 'CSSPerspective' in window, und sehen Sie einen Fallback über element.style.transform vor.
Werte, die keine Länge sind, etwa Zahlen ohne Einheit, Winkel oder Prozentwerte, lösen einen TypeError aus. Das gilt auch für spätere Zuweisungen an length.
Auf is2D kann man zwar schreiben, der Wert bleibt aber immer false.
Die Funktion perspective() wirkt nur auf das Element selbst. Sie unterscheidet sich von der CSS-Eigenschaft perspective, die für die Kindelemente gilt. Die Reihenfolge ist wichtig: Die Perspektive sollte im CSSTransformValue vor den Drehungen stehen, sonst fehlt die Tiefenwirkung.
Sehr kleine Werte (unter etwa 100px) verzerren stark. Große Werte wirken nahezu flach.

Siehe auch

CSSPerspective CSSTransformComponent CSSTransformValue CSSRotate CSSNumericValue new CSSMathNegate()