CSSPerspective — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSPerspective extends CSSTransformComponent

Beschreibung

CSSPerspective gehört zum CSS Typed Object Model (Houdini). Das Interface steht für die Funktion perspective() innerhalb eines transform-Werts, z. B. transform: perspective(500px) rotateY(45deg). Es erbt von CSSTransformComponent und ist normalerweise ein Element in einem CSSTransformValue.

Wichtig ist der Unterschied zur eigenständigen CSS-Eigenschaft perspective: Diese wirkt auf die Kindelemente eines Containers. Die Funktion perspective() dagegen gehört zur Transformationskette des Elements selbst, und dafür steht CSSPerspective.

Das Interface ist nützlich, wenn du 3D-Transformationen per JavaScript aufbauen oder ändern willst, ohne Zeichenketten zusammenzusetzen und zu parsen. Die Eigenschaft length enthält den Betrachtungsabstand als CSSNumericValue (z. B. CSS.px(800)). Diesen Wert kannst du direkt ändern, zum Beispiel für interaktive Effekte.

Diese Mitglieder werden von CSSTransformComponent geerbt:

is2D: bei CSSPerspective immer false, weil eine Perspektive nur im 3D-Raum Sinn ergibt. Ein Setzen dieser Eigenschaft wird ignoriert.
toMatrix(): gibt eine DOMMatrix zurück.
toString(): gibt die CSS-Schreibweise zurück, z. B. "perspective(500px)".

Parameter

Name	Typ	Default	Beschreibung
$length Pflicht	CSSNumericValue \| string		Betrachtungsabstand als Längenwert, z. B. `CSS.px(500)` oder `CSS.em(30)`. Neuere Implementierungen akzeptieren auch das Schlüsselwort `"none"` bzw. ein `CSSKeywordValue`. Ist der Wert keine Länge (z. B. `CSS.deg(10)`), wird ein `TypeError` ausgelöst.

Rückgabewert

Typ

CSSPerspective

Beschreibung

Der Konstruktor new CSSPerspective(length) gibt ein neues CSSPerspective-Objekt zurück. Die Eigenschaft length liefert den aktuellen Abstand als CSSNumericValue (bzw. als CSSKeywordValue bei none).

Beispiele

Instanz erzeugen und Eigenschaften lesen

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

console.log(p.toString());     // CSS-Schreibweise
console.log(p.length.value, p.length.unit);
console.log(p.is2D);           // bei Perspektive immer false

perspective(500px) 500 "px" false

3D-Karte per Typed OM transformieren

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

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

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

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

Perspektive abhängig von der Mausposition ändern

const stage = document.querySelector('.stage');
const perspective = new CSSPerspective(CSS.px(1000));
const rotate = new CSSRotate(CSS.number(0), CSS.number(1), CSS.number(0), CSS.deg(30));

stage.addEventListener('pointermove', (event) => {
  // Je weiter rechts, desto stärker der Tiefeneffekt (kleinerer Abstand)
  const ratio = event.clientX / window.innerWidth;
  perspective.length = CSS.px(300 + (1 - ratio) * 1200);
  stage.attributeStyleMap.set(
    'transform',
    new CSSTransformValue([perspective, rotate])
  );
});

CSSPerspective in einem vorhandenen transform finden

const el = document.querySelector('.box');
el.style.transform = 'perspective(600px) rotateX(20deg)';

const value = el.attributeStyleMap.get('transform');
for (const component of value) {
  if (component instanceof CSSPerspective) {
    console.log('Abstand:', component.length.toString());
  }
}

Abstand: 600px

// Wichtig · Fallstricke

Browserunterstützung: Chromium-basierte Browser (Chrome, Edge, Opera) ab Version 66 und Safari ab 16.4. Firefox unterstützt das CSS Typed OM derzeit nicht. Prüfe die Unterstützung vorab mit if ('CSSPerspective' in window) und greife sonst auf element.style.transform = '...' zurück.
Verwechsle die Funktion perspective() nicht mit der gleichnamigen CSS-Eigenschaft perspective. Diese wird im Typed OM nicht als CSSPerspective dargestellt, sondern als CSSUnitValue bzw. CSSKeywordValue.
Die Reihenfolge im CSSTransformValue ist entscheidend. perspective() sollte normalerweise vor Rotationen und Verschiebungen stehen, sonst gibt es keinen sichtbaren Tiefeneffekt.
Ist der Abstand sehr klein (nahe 0px), entstehen extreme Verzerrungen. Negative Werte sind in CSS ungültig.
Wird length geändert, aktualisiert das den Stil nicht automatisch. Du musst den CSSTransformValue danach erneut mit attributeStyleMap.set() zuweisen.
computedStyleMap().get('transform') liefert je nach Browser eventuell eine aufgelöste Matrix statt der einzelnen Funktionen. Einzelne CSSPerspective-Objekte bekommst du zuverlässig über attributeStyleMap.

Siehe auch

CSSPropertyRule CDATASection CSSPageRule CSSRotate CSSRuleList