SVGCircleElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGCircleElement extends SVGGeometryElement

Beschreibung

SVGCircleElement ist die DOM-Schnittstelle für das SVG-Element <circle>. Sie erbt von SVGGeometryElement (und damit von SVGGraphicsElement, SVGElement, Element und EventTarget). Deshalb stehen Geometrie-Methoden wie getTotalLength(), getPointAtLength(), isPointInFill() und getBBox() direkt zur Verfügung.

Die Schnittstelle selbst definiert drei schreibgeschützte Eigenschaften vom Typ SVGAnimatedLength:

cx: x-Koordinate des Mittelpunkts
cy: y-Koordinate des Mittelpunkts
r: Radius

Jede dieser Eigenschaften hat einen baseVal (den gesetzten Basiswert, also schreibbar) und einen animVal (den aktuellen Wert während einer SMIL-Animation, nur lesbar). Den numerischen Wert in Benutzereinheiten erhältst du über circle.r.baseVal.value.

Du brauchst die Schnittstelle, wenn du Kreise per JavaScript erzeugst, animierst oder vermisst, etwa für Diagramme, Fortschrittsringe, Datenpunkte in Scatterplots oder interaktive Grafiken. Neue Kreise werden immer mit document.createElementNS("http://www.w3.org/2000/svg", "circle") angelegt. Einen öffentlichen Konstruktor gibt es nicht.

Parameter

Name	Typ	Beschreibung
$cx	SVGAnimatedLength	Schreibgeschützte Eigenschaft: x-Koordinate des Mittelpunkts. Wert über `cx.baseVal.value` lesen oder setzen.
$cy	SVGAnimatedLength	Schreibgeschützte Eigenschaft: y-Koordinate des Mittelpunkts.
$r	SVGAnimatedLength	Schreibgeschützte Eigenschaft: Radius. Bei `0` wird nichts gezeichnet, negative Werte sind ein Fehler.

Rückgabewert

Typ

SVGCircleElement

Beschreibung

Wird von document.createElementNS(SVG_NS, "circle") oder von DOM-Abfragen wie querySelector("circle") zurückgegeben.

Beispiele

Kreis per JavaScript erzeugen

const SVG_NS = "http://www.w3.org/2000/svg";

const svg = document.createElementNS(SVG_NS, "svg");
svg.setAttribute("width", "200");
svg.setAttribute("height", "200");

const circle = document.createElementNS(SVG_NS, "circle");
circle.setAttribute("cx", "100");
circle.setAttribute("cy", "100");
circle.setAttribute("r", "50");
circle.setAttribute("fill", "tomato");

svg.append(circle);
document.body.append(svg);

console.log(circle instanceof SVGCircleElement);
console.log(circle.r.baseVal.value);

true 50

Radius über baseVal ändern und Umfang messen

const circle = document.querySelector("circle");

// Radius direkt über die DOM-Schnittstelle setzen
circle.r.baseVal.value = 40;

console.log(circle.getAttribute("r"));
// getTotalLength() stammt aus SVGGeometryElement
console.log(circle.getTotalLength().toFixed(2));

40 251.33

Fortschrittsring mit stroke-dasharray

const SVG_NS = "http://www.w3.org/2000/svg";
const ring = document.createElementNS(SVG_NS, "circle");
Object.entries({ cx: 60, cy: 60, r: 50, fill: "none", stroke: "steelblue", "stroke-width": 10 })
  .forEach(([k, v]) => ring.setAttribute(k, v));

const svg = document.createElementNS(SVG_NS, "svg");
svg.setAttribute("viewBox", "0 0 120 120");
svg.append(ring);
document.body.append(svg);

const setProgress = (percent) => {
  const circumference = 2 * Math.PI * ring.r.baseVal.value;
  ring.style.strokeDasharray = `${circumference}`;
  ring.style.strokeDashoffset = `${circumference * (1 - percent / 100)}`;
};

setProgress(75);
console.log(ring.style.strokeDashoffset);

78.53981633974483

Klick-Prüfung mit isPointInFill

const circle = document.querySelector("circle");
const svg = circle.ownerSVGElement;

const point = svg.createSVGPoint();
point.x = 100;
point.y = 100;

// Liegt der Punkt (in Benutzerkoordinaten) im Kreis?
console.log(circle.isPointInFill(point));

true

// Wichtig · Fallstricke

Namensraum: document.createElement(\"circle\") erzeugt ein HTMLUnknownElement, das nicht gezeichnet wird. Nimm immer createElementNS mit http://www.w3.org/2000/svg.
Nur lesbar: circle.r = 10 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Setze stattdessen circle.r.baseVal.value oder nutze setAttribute(\"r\", ...).
Einheiten: Wenn ein Wert in Prozent oder em angegeben ist, liefert baseVal.value Benutzereinheiten. Die Originalangabe steht in baseVal.valueAsString. Prozentangaben für r beziehen sich auf die normierte Diagonale des Viewports.
CSS-Geometrie: In modernen Browsern (SVG 2) lassen sich cx, cy und r auch als CSS-Eigenschaften setzen und per CSS animieren. animVal spiegelt aber nur SMIL-Animationen wider, keine CSS-Animationen.
Kompatibilität: Die Schnittstelle wird in allen Browsern unterstützt. isPointInFill() und isPointInStroke() sind neuer, sie sind seit etwa 2019/2020 in allen großen Browsern verfügbar.
Performance: Tausende einzelne <circle>-Knoten belasten das DOM. Bei sehr vielen Datenpunkten ist Canvas meist die bessere Wahl.

Siehe auch

SVGTitleElement SVGFETileElement SVGImageElement SVGLineElement SVGStyleElement