DOMPointReadOnly.z — Eigenschaft · JavaScript-Referenz

Signatur

DOMPointReadOnly.z

Beschreibung

Die Eigenschaft z von DOMPointReadOnly gibt die Tiefenkoordinate eines Punkts zurück. Positive Werte zeigen nach den CSS-Konventionen zum Betrachter hin, negative vom Betrachter weg. Bei rein zweidimensionalen Punkten ist z standardmäßig 0.

Die Eigenschaft ist schreibgeschützt: Eine Zuweisung hat keine Wirkung und wirft im Strict Mode einen TypeError. Wer den Wert ändern will, nutzt stattdessen DOMPoint, bei dem z beschreibbar ist, oder erzeugt über DOMPointReadOnly.fromPoint() bzw. den Konstruktor einen neuen Punkt.

Relevant wird z vor allem bei 3D-Transformationen mit DOMMatrix/DOMMatrixReadOnly (z. B. matrix.transformPoint() bei translateZ, rotate3d oder perspective), in WebXR (Position im Raum über XRRigidTransform.position) und bei der Umrechnung von Koordinaten zwischen CSS-Transformationen.

Rückgabewert

Typ

number

Beschreibung

Die z-Koordinate als Gleitkommazahl mit doppelter Genauigkeit (unrestricted double). Kann auch NaN oder ±Infinity sein. Standardwert: 0.

Beispiele

z-Koordinate eines Punkts auslesen

const point = new DOMPointReadOnly(10, 20, 30, 1);
console.log(point.z);

// Ohne Angabe ist z = 0
const flat = new DOMPointReadOnly(5, 5);
console.log(flat.z);

30 0

Schreibschutz: Zuweisung wird ignoriert

'use strict';
const p = new DOMPointReadOnly(0, 0, 5);
try {
  p.z = 100;
} catch (err) {
  console.log(err instanceof TypeError); // Getter ohne Setter
}
console.log(p.z);

// Veränderbare Kopie erzeugen
const editable = DOMPoint.fromPoint(p);
editable.z = 100;
console.log(editable.z);

true 5 100

Punkt durch 3D-Transformation schicken

const matrix = new DOMMatrixReadOnly()
  .translate(0, 0, 50)   // 50px nach vorne
  .rotate(0, 90, 0);     // 90° um die y-Achse

const origin = new DOMPointReadOnly(10, 0, 0);
const moved = matrix.transformPoint(origin);

console.log(moved.z.toFixed(2));

40.00

Abstand zweier Punkte im Raum

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

const a = new DOMPointReadOnly(0, 0, 0);
const b = new DOMPointReadOnly(3, 4, 12);
console.log(distance3D(a, b));

13

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen an z werden im Sloppy Mode stillschweigend ignoriert und werfen im Strict Mode (auch in ES-Modulen und Klassen) einen TypeError. Für veränderbare Punkte DOMPoint verwenden.
Gleitkomma-Ungenauigkeit: Nach Rotationen entstehen oft Werte wie 6.123e-16 statt 0. Beim Vergleich eine Toleranz (Epsilon) oder toFixed() nutzen.
Homogene Koordinaten: Bei perspektivischen Matrizen ist w nach transformPoint() ggf. ungleich 1. Die tatsächliche Tiefe ergibt sich dann aus z / w.
Keine Validierung: NaN und Infinity werden akzeptiert.
Kompatibilität: in allen modernen Browsern sowie in Web Workern verfügbar. Der Konstruktor new DOMPointReadOnly() wird in sehr alten Edge-Versionen (Legacy) nicht unterstützt. In Node.js gibt es die Schnittstelle nicht.

Siehe auch

DOMPointReadOnly DOMPointReadOnly.x DOMPointReadOnly.y DOMPointReadOnly.w DOMPoint DOMPointReadOnly.fromPoint() DOMMatrixReadOnly.transformPoint()