DOMPoint.z — Eigenschaft · JavaScript-Referenz

Signatur

DOMPoint.z

Beschreibung

Die Eigenschaft z eines DOMPoint gibt die Tiefen-Koordinate eines Punktes an. Positive Werte zeigen dabei in Richtung des Betrachters, negative Werte vom Betrachter weg. Das entspricht der Konvention von CSS-3D-Transformationen wie translateZ().

Im Gegensatz zu DOMPointReadOnly.z lässt sich der Wert bei DOMPoint auch schreiben. Beim Zuweisen wird der Wert in eine Gleitkommazahl (unrestricted double) umgewandelt. NaN und Infinity sind deshalb ebenfalls erlaubt.

z spielt vor allem dann eine Rolle, wenn Punkte mit einer 3D-Matrix (DOMMatrix) transformiert werden, zum Beispiel mit matrixTransform(). Auch bei WebXR-Positionsdaten (XRRigidTransform.position) und bei der Umrechnung von Koordinaten zwischen 3D-transformierten Elementen wird die Eigenschaft gebraucht. Bei reinen 2D-Anwendungen bleibt z meistens beim Standardwert 0.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Neuer Wert der Tiefen-Koordinate beim Zuweisen. Wird mit `Number()`-ähnlichen Regeln in eine Gleitkommazahl umgewandelt.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle z-Koordinate des Punktes als Gleitkommazahl mit doppelter Genauigkeit. Standardwert ist 0.

Beispiele

z-Koordinate lesen und setzen

const punkt = new DOMPoint(10, 20);
console.log(punkt.z); // Standardwert

punkt.z = -50; // 50 Einheiten vom Betrachter weg
console.log(punkt.z);

const punkt3d = new DOMPoint(1, 2, 3);
console.log(punkt3d.z);

0 -50 3

Punkt mit einer 3D-Matrix verschieben

const punkt = new DOMPoint(0, 0, 0);
// Verschiebung um 100 entlang der z-Achse
const matrix = new DOMMatrix().translate(0, 0, 100);

const ergebnis = punkt.matrixTransform(matrix);
console.log(ergebnis.z);
console.log(punkt.z); // Original bleibt unverändert

100 0

Abstand zwischen zwei 3D-Punkten berechnen

const distanz3d = (a, b) =>
  Math.hypot(b.x - a.x, b.y - a.y, b.z - a.z);

const kamera = new DOMPoint(0, 0, 500);
const objekt = new DOMPoint(300, 0, 100);

console.log(distanz3d(kamera, objekt));

500

Typumwandlung beim Zuweisen

const p = new DOMPoint();
p.z = '42.5';
console.log(p.z, typeof p.z);

p.z = 'abc';
console.log(p.z);

42.5 'number' NaN

// Wichtig · Fallstricke

Kein Einfluss auf die 2D-Darstellung: Wenn eine Matrix mit is2D === true angewendet wird, bleibt z im Wesentlichen unberührt. Die Tiefe ist nur mit echten 3D-Transformationen sinnvoll.
Keine Validierung: Ungültige Zuweisungen wie 'abc' führen stillschweigend zu NaN und werfen keinen Fehler. Nachfolgende Berechnungen liefern dann ebenfalls NaN.
Nur lesbar bei DOMPointReadOnly: Rückgabewerte mancher APIs sind vom Typ DOMPointReadOnly. Dort bleibt eine Zuweisung an z wirkungslos und wirft im Strict Mode einen TypeError. Mit DOMPoint.fromPoint() erzeugt man eine veränderbare Kopie.
Homogene Koordinaten: Bei perspektivischen Matrizen muss man eventuell durch w teilen, um die tatsächliche z-Position zu erhalten.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt, auch in Web Workern. Der ältere Internet Explorer kennt DOMPoint nicht. Node.js stellt die Schnittstelle nicht nativ bereit.

Siehe auch

DOMPoint DOMPoint.x DOMPoint.y DOMPoint.w DOMPointReadOnly.z DOMPointReadOnly.prototype.matrixTransform() DOMMatrix