DOMPointReadOnly — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMPointReadOnly

Beschreibung

DOMPointReadOnly beschreibt einen Punkt in einem 2D- oder 3D-Koordinatensystem über die schreibgeschützten Eigenschaften x, y, z und w. Die Komponente w ist der homogene Perspektivwert und steht standardmäßig auf 1. Die veränderbare Variante DOMPoint erbt von dieser Schnittstelle.

Du nutzt DOMPointReadOnly, wenn ein Punkt nach dem Anlegen nicht mehr geändert werden soll. Das ist zum Beispiel bei Rückgabewerten oder Konstanten sinnvoll. Mit der Methode matrixTransform() wendest du eine DOMMatrix auf den Punkt an. Du erhältst dann einen neuen DOMPoint, das Original bleibt unverändert. toJSON() liefert ein einfaches Objekt mit allen vier Werten.

Einen neuen Punkt legst du entweder mit dem Konstruktor new DOMPointReadOnly(x, y, z, w) an oder mit der statischen Methode DOMPointReadOnly.fromPoint(obj). Diese übernimmt ein beliebiges Objekt mit den Eigenschaften x/y/z/w, also etwa ein Objekt vom Typ DOMPointInit. Typische Einsatzbereiche sind Canvas-, SVG- und WebXR-Geometrie sowie die Umrechnung von Koordinaten mit CSS-Transformationsmatrizen.

Parameter

Name	Typ	Default	Beschreibung
$x	number	0	X-Koordinate (Konstruktor-Argument).
$y	number	0	Y-Koordinate.
$z	number	0	Z-Koordinate (Tiefe). Bei reinen 2D-Punkten `0`.
$w	number	1	Perspektivkomponente in homogenen Koordinaten.

Rückgabewert

Typ

DOMPointReadOnly

Beschreibung

Eine neue, unveränderliche Punkt-Instanz.

Beispiele

Punkt erzeugen und auslesen

const p = new DOMPointReadOnly(10, 20);
console.log(p.x, p.y, p.z, p.w);

// Zuweisungen werden ignoriert (im Strict Mode: TypeError)
try {
  'use strict';
  p.x = 99;
} catch (e) {
  console.log(e instanceof TypeError);
}
console.log(p.x);

10 20 0 1 true 10

Punkt mit einer Matrix transformieren

const origin = DOMPointReadOnly.fromPoint({ x: 50, y: 0 });

// Um 90 Grad drehen und danach um (100, 100) verschieben
const matrix = new DOMMatrix().translate(100, 100).rotate(90);
const moved = origin.matrixTransform(matrix);

console.log(Math.round(moved.x), Math.round(moved.y));
console.log(moved instanceof DOMPoint);
console.log(origin.x); // Original bleibt unverändert

100 150 true 50

Mauskoordinaten in das lokale System eines Elements umrechnen

const box = document.querySelector('#box');

box.addEventListener('click', (event) => {
  // Aktuelle CSS-Transformation des Elements auslesen
  const m = new DOMMatrix(getComputedStyle(box).transform);
  const rect = box.getBoundingClientRect();
  const clickPoint = new DOMPointReadOnly(
    event.clientX - rect.left,
    event.clientY - rect.top
  );
  // Mit der inversen Matrix zurückrechnen
  const local = clickPoint.matrixTransform(m.inverse());
  console.log(JSON.stringify(local.toJSON()));
});

// Wichtig · Fallstricke

Schreibschutz: Zuweisungen an x, y, z oder w ignoriert der Browser im Sloppy Mode ohne Fehlermeldung. Im Strict Mode, also auch in ES-Modulen, lösen sie einen TypeError aus. Für veränderbare Punkte verwendest du DOMPoint.
matrixTransform() gibt immer einen DOMPoint zurück, keinen DOMPointReadOnly. Das Ergebnis wird nicht durch w geteilt. Bei perspektivischen Matrizen musst du die Division durch w selbst vornehmen.
Die Werte sind Gleitkommazahlen doppelter Genauigkeit. Nach Drehungen entstehen Rundungsfehler wie 6.1e-15. Runde die Werte deshalb, bevor du sie vergleichst.
Kompatibilität: Chrome 61+, Firefox 69+ und Safari 10.1+ unterstützen die Schnittstelle. Außerdem ist sie in Web Workern verfügbar. Node.js stellt sie nicht nativ bereit.

Siehe auch

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