new DOMPointReadOnly() — Methode · JavaScript-Referenz

Signatur

new DOMPointReadOnly(x, y, z, w)

Beschreibung

Der Konstruktor DOMPointReadOnly() legt einen Punkt mit den Koordinaten x, y, z und der Perspektivkomponente w an. Alle Werte sind nach der Erzeugung schreibgeschützt: Zuweisungen an die Eigenschaften werden ignoriert. Im Strict Mode lösen sie einen TypeError aus.

Solche unveränderlichen Punkte eignen sich gut für Koordinaten, die sich nicht versehentlich ändern sollen, zum Beispiel Referenzpunkte, Konstanten oder Werte, die man an Bibliotheken übergibt. Mit matrixTransform() lässt sich ein Punkt durch eine DOMMatrix transformieren. Das Ergebnis ist dann ein neuer, veränderbarer DOMPoint.

Fehlende Argumente werden auf Standardwerte gesetzt: x, y und z auf 0, w auf 1. Alle Argumente werden in Gleitkommazahlen umgewandelt (unrestricted double). Dadurch sind auch NaN und Infinity erlaubt. Brauchen Sie einen veränderbaren Punkt, verwenden Sie die Unterklasse DOMPoint.

Parameter

Name	Typ	Default	Beschreibung
$x	number	0	x-Koordinate des Punkts.
$y	number	0	y-Koordinate des Punkts.
$z	number	0	z-Koordinate (Tiefe) des Punkts.
$w	number	1	Perspektivkomponente (homogene Koordinate). Bei normalen 2D- und 3D-Punkten bleibt sie `1`.

Rückgabewert

Typ

DOMPointReadOnly

Beschreibung

Ein neues, schreibgeschütztes Punkt-Objekt mit den Eigenschaften x, y, z und w.

Beispiele

2D- und 3D-Punkte anlegen

const p2d = new DOMPointReadOnly(50, 100);
const p3d = new DOMPointReadOnly(10, 20, 30);
const origin = new DOMPointReadOnly();

console.log(p2d.x, p2d.y, p2d.z, p2d.w);
console.log(p3d.toJSON());
console.log(origin.x, origin.w);

50 100 0 1 { x: 10, y: 20, z: 30, w: 1 } 0 1

Schreibschutz der Eigenschaften

'use strict';
const anchor = new DOMPointReadOnly(5, 5);

try {
  anchor.x = 99;
} catch (err) {
  console.log(err instanceof TypeError); // Zuweisung verboten
}
console.log(anchor.x);

true 5

Punkt mit einer Matrix transformieren

const corner = new DOMPointReadOnly(100, 0);
// Drehung um 90° und Verschiebung um (10, 10)
const matrix = new DOMMatrix().translate(10, 10).rotate(90);

const moved = corner.matrixTransform(matrix);
console.log(moved instanceof DOMPoint);
console.log(Math.round(moved.x), Math.round(moved.y));

true 10 110

Aus einem Objekt erzeugen mit fromPoint()

// z. B. Mausposition aus einem Event
const pos = { x: 320, y: 240 };
const point = DOMPointReadOnly.fromPoint(pos);

console.log(point.x, point.y, point.z, point.w);

320 240 0 1

// Wichtig · Fallstricke

Kein tiefer Schutz: „Read-only“ bezieht sich nur auf die Eigenschaften dieses einen Objekts. DOMPoint erbt von DOMPointReadOnly. Deshalb liefert instanceof DOMPointReadOnly auch für veränderbare Punkte true.
Nur mit new aufrufen: Ohne new wird ein TypeError ausgelöst.
Keine Prüfung der Werte: Nicht-numerische Argumente werden in Zahlen umgewandelt. new DOMPointReadOnly('a') ergibt deshalb x = NaN, ohne dass ein Fehler auftritt.
Serialisierung: JSON.stringify() funktioniert über toJSON(). Das Objekt lässt sich außerdem per structuredClone() und postMessage() übertragen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Workern. Den Internet Explorer unterstützt die API nicht. In Node.js gibt es sie nicht nativ.

Siehe auch

DOMPointReadOnly DOMPoint DOMPointReadOnly.fromPoint() DOMPointReadOnly.prototype.matrixTransform() DOMMatrix DOMRectReadOnly DOMQuad