CSSPerspective.length — Eigenschaft · JavaScript-Referenz

Signatur

CSSPerspective.length

Beschreibung

Die Eigenschaft length der Schnittstelle CSSPerspective gehört zum CSS Typed Object Model. Sie entspricht dem Argument der CSS-Transformationsfunktion perspective(), also z. B. den 800px in transform: perspective(800px) rotateY(30deg). Der Wert gibt an, wie weit der Betrachter von der Ebene z=0 entfernt ist. Kleine Werte erzeugen eine starke, verzerrte 3D-Wirkung, große Werte eine flache.

Anders als bei der String-Bearbeitung von element.style.transform bekommst du hier ein typisiertes Objekt (CSSUnitValue oder CSSMathValue) mit value und unit. Du musst also keine Zeichenketten zerlegen oder neu zusammensetzen. Das ist praktisch für Animationen, interaktive 3D-Effekte oder Werkzeuge, die Transformationen gezielt auslesen und ändern.

Die Eigenschaft ist les- und schreibbar. Beim Setzen muss der Wert vom Typ Länge sein, zum Beispiel CSS.px(500), CSS.em(30) oder ein berechneter Wert wie CSS.px(200).add(CSS.vw(10)). Winkel, reine Zahlen oder Prozentwerte werden mit einem TypeError abgelehnt. Neuere Fassungen der Spezifikation erlauben außerdem das Schlüsselwort none als CSSKeywordValue.

Parameter

Name	Typ	Default	Beschreibung
$value (beim Setzen) Pflicht	CSSNumericValue \| CSSKeywordValue		Neue Perspektiv-Entfernung. Muss eine Länge sein, z. B. `CSS.px(600)`. Neuere Implementierungen akzeptieren auch `new CSSKeywordValue('none')`.

Rückgabewert

Typ

CSSNumericValue | CSSKeywordValue

Beschreibung

Die aktuelle Perspektiv-Entfernung. Meist ist das ein CSSUnitValue mit value und unit, bei calc()-Ausdrücken ein CSSMathValue.

Beispiele

CSSPerspective erzeugen und length auslesen

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

console.log(persp.length.value); // Zahlenwert
console.log(persp.length.unit);  // Einheit
console.log(persp.toString());   // als CSS-Text

500 px perspective(500px)

Perspektive eines Elements per Typed OM ändern

// HTML: <div id="karte" style="transform: perspective(800px) rotateY(30deg)"></div>
const karte = document.querySelector('#karte');

const transform = karte.attributeStyleMap.get('transform'); // CSSTransformValue
const persp = [...transform].find((t) => t instanceof CSSPerspective);

console.log(persp.length.toString());

// Entfernung halbieren -> stärkerer 3D-Effekt
persp.length = CSS.px(persp.length.value / 2);
karte.attributeStyleMap.set('transform', transform);

console.log(karte.style.transform);

800px perspective(400px) rotateY(30deg)

Interaktive Perspektive mit Schieberegler

// HTML: <input type="range" id="tiefe" min="100" max="2000" value="800">
//       <div id="box"></div>
const box = document.querySelector('#box');
const regler = document.querySelector('#tiefe');

const persp = new CSSPerspective(CSS.px(Number(regler.value)));
const rotation = new CSSRotate(CSS.number(0), CSS.number(1), CSS.number(0), CSS.deg(40));
const transform = new CSSTransformValue([persp, rotation]);
box.attributeStyleMap.set('transform', transform);

regler.addEventListener('input', () => {
  persp.length = CSS.px(Number(regler.value));
  box.attributeStyleMap.set('transform', transform);
});

Ungültige Typen führen zu einem TypeError

const persp = new CSSPerspective(CSS.px(300));

try {
  persp.length = CSS.deg(45); // Winkel statt Länge
} catch (err) {
  console.log(err.name);
}

// Berechnete Längen sind erlaubt
persp.length = CSS.px(200).add(CSS.vw(10));
console.log(persp.toString());

TypeError perspective(calc(200px + 10vw))

// 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 derzeit nicht. Prüfe die Verfügbarkeit mit if ('CSSPerspective' in window) und greife sonst auf element.style.transform mit Zeichenketten zurück.
Nur Längen: Werte wie CSS.deg(), CSS.number() oder CSS.percent() werfen beim Setzen oder im Konstruktor einen TypeError. Das gilt auch für einen einfachen JavaScript-number.
Nicht automatisch live: Wenn du length änderst, ändert sich nur das JavaScript-Objekt. Damit die Darstellung sich ändert, musst du den CSSTransformValue erneut mit attributeStyleMap.set('transform', …) zuweisen.
Nicht verwechseln: Die Funktion perspective() in transform wirkt auf das Element selbst. Die CSS-Eigenschaft perspective dagegen wirkt auf die Kindelemente. CSSPerspective steht nur für die Funktion.
computedStyleMap().get('transform') liefert je nach Browser eine aufgelöste Matrix statt der einzelnen Bestandteile. Einzelne CSSPerspective-Objekte bekommst du zuverlässig über attributeStyleMap.

Siehe auch

CSSPerspective CSSTransformValue CSSTransformComponent CSSNumericValue CSSUnitValue CSSRotate