DOMPoint — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMPoint extends DOMPointReadOnly

Beschreibung

DOMPoint gehört zur Geometry-Interfaces-Spezifikation und beschreibt einen Punkt in einem Koordinatensystem. Er hat die Eigenschaften x, y, z (Standardwert jeweils 0) und w (Perspektive, Standardwert 1). Anders als bei der Elternschnittstelle DOMPointReadOnly kann man alle vier Werte nachträglich ändern.

Gebraucht wird ein DOMPoint vor allem zusammen mit DOMMatrix: Mit point.matrixTransform(matrix) wendet man eine Transformation (Verschiebung, Drehung, Skalierung, 3D-Projektion) auf einen Punkt an. Typische Einsätze sind das Umrechnen von Mauskoordinaten in das lokale Koordinatensystem eines transformierten Elements, Berechnungen auf dem Canvas (ctx.getTransform() liefert eine DOMMatrix) und die Geometrie von SVG-Grafiken.

Es gibt zwei Wege, einen Punkt zu erzeugen: den Konstruktor new DOMPoint(x, y, z, w) und die statische Methode DOMPoint.fromPoint(obj), die ein beliebiges Objekt mit den passenden Eigenschaften übernimmt. Mit toJSON() erhält man ein einfaches Objekt, das sich serialisieren lässt.

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	Perspektivwert (homogene Koordinate). Bei normalen 2D- und 3D-Punkten bleibt er `1`.

Rückgabewert

Typ

DOMPoint

Beschreibung

Ein neues, veränderbares DOMPoint-Objekt.

Beispiele

Punkt erzeugen und verändern

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

p.x += 5;
p.z = 3;
console.log(JSON.stringify(p.toJSON()));

10 20 0 1 {"x":15,"y":20,"z":3,"w":1}

Punkt mit einer DOMMatrix transformieren

// Um 50/0 verschieben, dann um 90° drehen
const matrix = new DOMMatrix().translate(50, 0).rotate(90);
const point = new DOMPoint(10, 0);

const result = point.matrixTransform(matrix);
console.log(Math.round(result.x), Math.round(result.y));

50 10

Mausposition in Canvas-Koordinaten umrechnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
ctx.translate(100, 100);
ctx.scale(2, 2);

canvas.addEventListener('click', (event) => {
  const rect = canvas.getBoundingClientRect();
  const screenPoint = new DOMPoint(event.clientX - rect.left, event.clientY - rect.top);
  // Aktuelle Transformation umkehren -> Koordinaten im Zeichenraum
  const local = screenPoint.matrixTransform(ctx.getTransform().inverse());
  console.log(`Zeichenkoordinaten: ${local.x}, ${local.y}`);
});

z. B. bei Klick auf (140, 120): Zeichenkoordinaten: 20, 10

DOMPoint.fromPoint aus einem einfachen Objekt

const data = { x: 3, y: 4 };
const p = DOMPoint.fromPoint(data);
const distance = Math.hypot(p.x, p.y);
console.log(p instanceof DOMPoint, distance);

true 5

// Wichtig · Fallstricke

matrixTransform() verändert den Punkt nicht, sondern gibt einen neuen DOMPoint zurück.
Ist die Matrix eine echte 3D-/Perspektivmatrix, kann w ungleich 1 werden. Die Werte werden dann nicht automatisch durch w geteilt. Für kartesische Koordinaten muss man selbst x / w, y / w rechnen.
Nichtnumerische Werte werden in Zahlen umgewandelt. Aus new DOMPoint('a') wird x = NaN, ohne dass ein Fehler auftritt.
Das veraltete SVGPoint (svg.createSVGPoint()) ist in modernen Browsern bereits als DOMPoint umgesetzt. Neuer Code sollte direkt new DOMPoint() verwenden.
Browserunterstützung: Chrome 61+, Firefox 69+, Safari 10.1+ und Edge 79+. Die Schnittstelle gibt es auch in Web Workern. Im Internet Explorer fehlt sie; in Node.js gibt es sie nicht nativ.

Siehe auch

DOMPointReadOnly DOMMatrix DOMRect DOMQuad DOMPointReadOnly.prototype.matrixTransform() CanvasRenderingContext2D.prototype.getTransform()