SVGSVGElement.checkEnclosure() — Methode · JavaScript-Referenz

Signatur

SVGSVGElement.prototype.checkEnclosure(element, rect)

Beschreibung

checkEnclosure() wird auf einem <svg>-Element aufgerufen und gibt true zurück, wenn der gerenderte Inhalt des übergebenen Elements vollständig im angegebenen Rechteck liegt. Das Rechteck wird im Benutzerkoordinatensystem (User Space) des <svg>-Elements angegeben, auf dem die Methode aufgerufen wird. Transformationen der Kindelemente werden dabei berücksichtigt.

Typische Einsatzfälle sind Rahmenauswahl in Editoren und Diagramm-Werkzeugen (z. B. alle Formen markieren, die komplett in einem aufgezogenen Rechteck liegen), einfache Kollisions- oder Bereichsprüfungen sowie Tests, ob ein Element vollständig in einem sichtbaren Ausschnitt liegt.

Das Gegenstück ist checkIntersection(): Dort reicht eine teilweise Überlappung. Mit getEnclosureList() bekommt man direkt alle umschlossenen Elemente als Liste. Das Rechteck erzeugt man am zuverlässigsten mit svg.createSVGRect() und setzt danach x, y, width und height.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	SVGElement		Das zu prüfende Element, z. B. ein `<rect>`, `<circle>` oder `<g>`.
$rect Pflicht	SVGRect \| DOMRectReadOnly		Das Vergleichsrechteck im Benutzerkoordinatensystem des `<svg>`-Elements. Am sichersten per `svg.createSVGRect()` erzeugen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der gerenderte Inhalt des Elements vollständig im Rechteck liegt, sonst false.

Beispiele

Einfache Prüfung mit createSVGRect()

const svg = document.querySelector('svg');
const box = document.querySelector('#box'); // <rect x="20" y="20" width="50" height="50">

const area = svg.createSVGRect();
area.x = 0;
area.y = 0;
area.width = 100;
area.height = 100;

console.log(svg.checkEnclosure(box, area));

area.width = 60; // rechte Kante des Rechtecks (70) liegt jetzt außerhalb
console.log(svg.checkEnclosure(box, area));

true false

Rahmenauswahl in einem Diagramm-Editor

const svg = document.querySelector('#editor');
const shapes = [...svg.querySelectorAll('.shape')];

// Mauskoordinaten in SVG-Benutzerkoordinaten umrechnen
const toSvgPoint = (evt) => {
  const pt = new DOMPoint(evt.clientX, evt.clientY);
  return pt.matrixTransform(svg.getScreenCTM().inverse());
};

let start = null;

svg.addEventListener('pointerdown', (evt) => {
  start = toSvgPoint(evt);
});

svg.addEventListener('pointerup', (evt) => {
  if (!start) return;
  const end = toSvgPoint(evt);
  const sel = svg.createSVGRect();
  sel.x = Math.min(start.x, end.x);
  sel.y = Math.min(start.y, end.y);
  sel.width = Math.abs(end.x - start.x);
  sel.height = Math.abs(end.y - start.y);

  for (const shape of shapes) {
    shape.classList.toggle('selected', svg.checkEnclosure(shape, sel));
  }
  start = null;
});

Funktionsprüfung mit Fallback über getBBox()

const isEnclosed = (svg, el, { x, y, width, height }) => {
  if (typeof svg.checkEnclosure === 'function') {
    const r = svg.createSVGRect();
    Object.assign(r, { x, y, width, height });
    return svg.checkEnclosure(el, r);
  }
  // Fallback (z. B. Firefox): ignoriert Transformationen des Elements!
  const b = el.getBBox();
  return b.x >= x && b.y >= y &&
         b.x + b.width <= x + width &&
         b.y + b.height <= y + height;
};

const svg = document.querySelector('svg');
console.log(isEnclosed(svg, svg.querySelector('circle'), { x: 0, y: 0, width: 200, height: 200 }));

true

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (Chrome, Edge, Opera) und Safari unterstützen die Methode. Firefox hat sie nicht implementiert. Deshalb vorher mit typeof svg.checkEnclosure === 'function' prüfen und einen Fallback bereithalten.
In manchen Browsern führt ein normales DOMRect (z. B. new DOMRect()) zu einem TypeError, weil dort ein SVGRect erwartet wird. Mit svg.createSVGRect() ist man auf der sicheren Seite.
Das Rechteck gilt im Benutzerkoordinatensystem des <svg>-Elements, nicht in Bildschirmpixeln. Maus- oder Zeigerkoordinaten muss man vorher umrechnen, etwa mit getScreenCTM().inverse(). Das gilt vor allem bei viewBox und Skalierung.
Browser prüfen meist nur den Begrenzungsrahmen (Bounding Box) und nicht die genaue Geometrie. Ein Kreis kann also als „nicht umschlossen“ gelten, obwohl nur die leeren Ecken seines Rahmens herausragen. Ob die Strichbreite (stroke) mitzählt, kann je nach Browser verschieden sein.
Nicht gerenderte Elemente (z. B. mit display: none oder innerhalb von <defs>) liefern in der Regel false.

Siehe auch

SVGSVGElement SVGSVGElement.checkIntersection() SVGSVGElement.createSVGRect() SVGGraphicsElement.getBBox() SVGSVGElement.createSVGAngle()