CanvasRenderingContext2D.ellipse() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle, counterclockwise)

Beschreibung

ellipse() ist die Verallgemeinerung von arc(). Statt eines einzigen Radius gibt es zwei Halbachsen (radiusX, radiusY). Zusätzlich lässt sich die ganze Ellipse um ihren Mittelpunkt drehen. So zeichnet man Ovale, gedrehte Ellipsen, Teilbögen und Tortensegmente, ohne das Koordinatensystem vorher mit scale() oder rotate() verzerren zu müssen.

Die Methode zeichnet selbst nichts, sondern ergänzt nur den aktuellen Pfad. Sichtbar wird er erst durch stroke() oder fill(). Enthält der Unterpfad schon Punkte, verbindet eine gerade Linie den letzten Punkt mit dem Startpunkt des Bogens. Deshalb ruft man vor jeder neuen Form meist beginPath() auf oder setzt mit moveTo() einen neuen Startpunkt.

Alle Winkel werden in Bogenmaß angegeben. Gemessen wird ab der positiven x-Achse der (gedrehten) Ellipse, bei counterclockwise = false im Uhrzeigersinn, weil die y-Achse im Canvas nach unten zeigt. Eine volle Ellipse erhält man mit 0 bis 2 * Math.PI.

Dieselbe Methode gibt es auch bei Path2D und OffscreenCanvasRenderingContext2D. Damit lassen sich elliptische Pfade wiederverwenden oder in Web Workern zeichnen.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number		x-Koordinate des Mittelpunkts der Ellipse.
$y Pflicht	number		y-Koordinate des Mittelpunkts der Ellipse.
$radiusX Pflicht	number		Radius der Hauptachse (vor der Drehung horizontal). Darf nicht negativ sein.
$radiusY Pflicht	number		Radius der Nebenachse (vor der Drehung vertikal). Darf nicht negativ sein.
$rotation Pflicht	number		Drehung der Ellipse um ihren Mittelpunkt, in Bogenmaß.
$startAngle Pflicht	number		Startwinkel in Bogenmaß, gemessen ab der x-Achse der Ellipse.
$endAngle Pflicht	number		Endwinkel in Bogenmaß.
$counterclockwise	boolean	false	Bei `true` wird der Bogen gegen den Uhrzeigersinn gezeichnet.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Methode ergänzt nur den aktuellen Pfad.

Beispiele

Gefülltes Oval zeichnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

ctx.beginPath();
// Mittelpunkt (150|75), Halbachsen 100 und 50, keine Drehung
ctx.ellipse(150, 75, 100, 50, 0, 0, 2 * Math.PI);
ctx.fillStyle = 'tomato';
ctx.fill();

Gedrehte Ellipse mit Umriss

const ctx = document.querySelector('canvas').getContext('2d');

const degToRad = (deg) => (deg * Math.PI) / 180;

ctx.beginPath();
// Um 45° gedreht
ctx.ellipse(150, 100, 80, 30, degToRad(45), 0, 2 * Math.PI);
ctx.lineWidth = 3;
ctx.strokeStyle = '#0066cc';
ctx.stroke();

Elliptisches Tortensegment (z. B. 3D-Diagramm)

const ctx = document.querySelector('canvas').getContext('2d');

const drawSlice = (cx, cy, start, end, color) => {
  ctx.beginPath();
  ctx.moveTo(cx, cy); // Vom Mittelpunkt aus starten
  ctx.ellipse(cx, cy, 120, 60, 0, start, end);
  ctx.closePath();
  ctx.fillStyle = color;
  ctx.fill();
};

drawSlice(150, 100, 0, Math.PI * 0.6, '#4caf50');
drawSlice(150, 100, Math.PI * 0.6, Math.PI * 1.4, '#ff9800');
drawSlice(150, 100, Math.PI * 1.4, Math.PI * 2, '#2196f3');

Wiederverwendbarer Pfad mit Path2D

const ctx = document.querySelector('canvas').getContext('2d');

const eye = new Path2D();
eye.ellipse(0, 0, 40, 20, 0, 0, 2 * Math.PI);

[[80, 60], [200, 60]].forEach(([x, y]) => {
  ctx.save();
  ctx.translate(x, y);
  ctx.stroke(eye);
  ctx.restore();
});

console.log(ctx.isPointInPath(eye, 0, 0));

true

// Wichtig · Fallstricke

Negative Radien lösen eine IndexSizeError-DOMException aus. Nicht endliche Werte wie NaN oder Infinity werden ohne Fehlermeldung ignoriert: Es wird dann nichts gezeichnet.
Winkel in Bogenmaß, nicht in Grad. Ein häufiger Fehler ist ellipse(…, 0, 360). Das funktioniert nur zufällig, weil Werte ab 2π als voller Umlauf gelten.
Ohne vorheriges beginPath() oder moveTo() entsteht eine ungewollte Verbindungslinie vom letzten Pfadpunkt zum Startpunkt des Bogens.
rotation dreht die Ellipse selbst. Start- und Endwinkel beziehen sich auf die bereits gedrehte Ellipse.
Kompatibilität: in allen modernen Browsern verfügbar, im Internet Explorer nicht. Als Ersatz dient dort save() + scale() + arc() + restore().

Siehe auch

CanvasRenderingContext2D.arc() CanvasRenderingContext2D.arcTo() CanvasRenderingContext2D.beginPath() CanvasRenderingContext2D.fill() CanvasRenderingContext2D.stroke() Path2D CanvasRenderingContext2D