</> programmierung.net
Start · Sprachen · JavaScript · Referenz · DOMQuad

DOMQuad

Schnittstelle

Ein <code>DOMQuad</code> besteht aus vier <code>DOMPoint</code>-Objekten, die die Ecken eines beliebigen, auch verdrehten oder verzerrten Vierecks beschreiben.

seit JavaScript Baseline: alle modernen Browser (auch in Web Worke Kategorie: webapi

Signatur

interface DOMQuad

Beschreibung

DOMQuad gehört zur Geometry-Interfaces-Spezifikation und steht neben DOMPoint, DOMRect und DOMMatrix. Ein DOMRect ist immer achsenparallel. Ein DOMQuad kann dagegen jedes Viereck darstellen, also auch gedrehte, gescherte oder perspektivisch verzerrte Flächen. Das ist der Fall, sobald eine CSS- oder Canvas-Transformation auf ein Rechteck angewendet wird.

Die vier Ecken liegen in den schreibgeschützten Eigenschaften p1, p2, p3 und p4. Jede davon ist ein DOMPoint. Die Referenz auf den Punkt lässt sich nicht austauschen, seine Koordinaten x, y, z und w kann man aber direkt ändern. Wichtige Mitglieder:

  • new DOMQuad(p1, p2, p3, p4): erzeugt ein Viereck aus vier Punkten.
  • DOMQuad.fromRect(rect): erzeugt ein Viereck aus einem Rechteck (Uhrzeigersinn, Start oben links).
  • DOMQuad.fromQuad(quad): erzeugt eine Kopie aus einem Objekt mit den Eigenschaften p1 bis p4.
  • getBounds(): gibt das kleinste achsenparallele DOMRect zurück, das alle vier Punkte umschließt.
  • toJSON(): wandelt das Viereck in ein einfaches, serialisierbares Objekt um.

Typische Anwendungsfälle sind die Kollisionserkennung mit transformierten Elementen, Treffertests in Canvas- oder SVG-Editoren, das Berechnen der Bounding-Box nach einer Rotation und die Weitergabe von Geometriedaten an Worker, zum Beispiel per postMessage.

Parameter

Name Typ Default Beschreibung
$p1 DOMPointInit {x: 0, y: 0, z: 0, w: 1} Erster Eckpunkt, üblicherweise oben links.
$p2 DOMPointInit {x: 0, y: 0, z: 0, w: 1} Zweiter Eckpunkt, üblicherweise oben rechts.
$p3 DOMPointInit {x: 0, y: 0, z: 0, w: 1} Dritter Eckpunkt, üblicherweise unten rechts.
$p4 DOMPointInit {x: 0, y: 0, z: 0, w: 1} Vierter Eckpunkt, üblicherweise unten links.

Rückgabewert

Typ
DOMQuad
Beschreibung
Ein neues DOMQuad-Objekt. Seine Eigenschaften p1 bis p4 sind DOMPoint-Instanzen.

Beispiele

Viereck erzeugen und Bounding-Box ermitteln

const quad = new DOMQuad(
  { x: 0, y: 0 },
  { x: 100, y: 20 },
  { x: 120, y: 80 },
  { x: 10, y: 60 }
);

console.log(quad.p3.x, quad.p3.y);

const { x, y, width, height } = quad.getBounds();
console.log({ x, y, width, height });
120 80 { x: 0, y: 0, width: 120, height: 80 }

Aus einem Rechteck erzeugen und serialisieren

const quad = DOMQuad.fromRect({ x: 10, y: 20, width: 100, height: 50 });

// Reihenfolge: oben links, oben rechts, unten rechts, unten links
const corners = [quad.p1, quad.p2, quad.p3, quad.p4]
  .map(({ x, y }) => `(${x}|${y})`);
console.log(corners.join(' '));

// Für postMessage oder JSON geeignet
console.log(JSON.stringify(quad.toJSON().p3));
(10|20) (110|20) (110|70) (10|70) {"x":110,"y":70,"z":0,"w":1}

Gedrehtes Rechteck: Ecken transformieren und Bounding-Box berechnen

const rect = { x: 0, y: 0, width: 100, height: 50 };
const matrix = new DOMMatrix().rotate(90); // 90° um den Ursprung

const base = DOMQuad.fromRect(rect);
const rotated = new DOMQuad(
  matrix.transformPoint(base.p1),
  matrix.transformPoint(base.p2),
  matrix.transformPoint(base.p3),
  matrix.transformPoint(base.p4)
);

const b = rotated.getBounds();
// Runden, weil cos(90°) nicht exakt 0 ist
console.log([b.x, b.y, b.width, b.height].map(Math.round));
[-50, 0, 50, 100]

Punkt eines Vierecks direkt verschieben

const quad = DOMQuad.fromRect({ x: 0, y: 0, width: 40, height: 40 });

// quad.p2 = ... ist nicht möglich, die Koordinaten sind aber änderbar
quad.p2.x += 20;
quad.p3.x += 20;

console.log(quad.getBounds().width);
60

// Wichtig · Fallstricke

  • Schreibgeschützte Punkte: p1 bis p4 kann man nicht neu zuweisen. Wer quad.p1 = new DOMPoint() schreibt, bekommt keine Wirkung (im Strict Mode einen TypeError). Die Koordinaten der vorhandenen Punkte lassen sich dagegen ändern.
  • getBounds() berücksichtigt nur x und y: Werte für z und w fließen nicht ein. Eine perspektivische Division durch w muss man vorher selbst durchführen.
  • Keine Transformationsmethode: DOMQuad hat kein eingebautes transform(). Jeden Punkt einzeln mit DOMMatrix.prototype.transformPoint() umrechnen.
  • Gleitkomma-Ungenauigkeit: Nach Rotationen entstehen Werte wie 6.1e-15 statt 0. Vor Vergleichen runden oder mit einer Toleranz arbeiten.
  • Kompatibilität: Das Interface selbst wird in allen modernen Browsern unterstützt, auch in Workern. Die Methoden, die ein DOMQuad liefern, etwa Element.getBoxQuads() und convertQuadFromNode(), sind experimentell und praktisch nur in Firefox hinter einem Flag verfügbar. In der Praxis erzeugt man DOMQuad-Objekte deshalb meist selbst.
  • Die Reihenfolge der Punkte wird nicht geprüft. Überkreuzte oder entartete Vierecke sind erlaubt.

Siehe auch

DOMRect Gamepad Comment DOMError DOMPoint
← Vorheriger Eintrag DOMPointReadOnly.z