CanvasRenderingContext2D.arc() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.arc(x, y, radius, startAngle, endAngle, counterclockwise)

Beschreibung

Mit arc() beschreibt man Kreise, Kreisbögen und Kreissegmente auf einem <canvas>. Der Bogen hat seinen Mittelpunkt bei (x, y) und den Radius radius. Er beginnt bei startAngle und endet bei endAngle. Beide Winkel werden im Bogenmaß angegeben und von der positiven x-Achse aus gemessen (also „3 Uhr“). Weil die y-Achse im Canvas nach unten zeigt, laufen positive Winkel im Uhrzeigersinn.

Die Methode zeichnet selbst nichts. Sie erweitert nur den aktuellen Pfad. Sichtbar wird er erst durch stroke() oder fill(). Gibt es im Sub-Pfad schon einen Punkt, verbindet arc() ihn automatisch mit einer geraden Linie mit dem Startpunkt des Bogens. Deshalb ruft man vor einem neuen Kreis normalerweise beginPath() oder moveTo() auf.

Einen Vollkreis erhält man mit startAngle = 0 und endAngle = 2 * Math.PI. Ist die Winkeldifferenz mindestens 2π, zeichnet die Methode immer einen vollständigen Kreis. Mit counterclockwise = true läuft der Bogen gegen den Uhrzeigersinn. So lassen sich zum Beispiel der größere oder kleinere Teil eines Kreises gezielt auswählen.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number		x-Koordinate des Kreismittelpunkts.
$y Pflicht	number		y-Koordinate des Kreismittelpunkts.
$radius Pflicht	number		Radius des Bogens. Muss ≥ 0 sein, sonst wird ein `IndexSizeError` geworfen.
$startAngle Pflicht	number		Startwinkel im Bogenmaß, gemessen von der positiven x-Achse.
$endAngle Pflicht	number		Endwinkel im Bogenmaß, gemessen von der positiven x-Achse.
$counterclockwise	boolean	false	Bei `true` wird der Bogen gegen den Uhrzeigersinn gezeichnet, sonst im Uhrzeigersinn.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Nur der aktuelle Pfad wird verändert.

Beispiele

Gefüllter Kreis mit Umrandung

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

ctx.beginPath();
ctx.arc(100, 75, 50, 0, 2 * Math.PI);
ctx.fillStyle = '#4caf50';
ctx.fill();
ctx.lineWidth = 4;
ctx.strokeStyle = '#1b5e20';
ctx.stroke();

Tortendiagramm aus Daten

const ctx = document.querySelector('canvas').getContext('2d');
const daten = [
  { wert: 40, farbe: '#e91e63' },
  { wert: 25, farbe: '#2196f3' },
  { wert: 35, farbe: '#ffc107' }
];
const summe = daten.reduce((s, d) => s + d.wert, 0);
const [cx, cy, r] = [150, 150, 100];

let start = -Math.PI / 2; // oben beginnen
for (const { wert, farbe } of daten) {
  const ende = start + (wert / summe) * 2 * Math.PI;
  ctx.beginPath();
  ctx.moveTo(cx, cy);          // Segment beginnt im Mittelpunkt
  ctx.arc(cx, cy, r, start, ende);
  ctx.closePath();
  ctx.fillStyle = farbe;
  ctx.fill();
  start = ende;
}

Fortschrittsring (Ladeanzeige)

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

const zeichneFortschritt = (prozent) => {
  ctx.clearRect(0, 0, 200, 200);
  ctx.lineWidth = 12;
  ctx.lineCap = 'round';

  // Hintergrundring
  ctx.beginPath();
  ctx.arc(100, 100, 70, 0, 2 * Math.PI);
  ctx.strokeStyle = '#ddd';
  ctx.stroke();

  // Fortschrittsbogen
  const start = -Math.PI / 2;
  ctx.beginPath();
  ctx.arc(100, 100, 70, start, start + (prozent / 100) * 2 * Math.PI);
  ctx.strokeStyle = '#3f51b5';
  ctx.stroke();

  ctx.font = '24px sans-serif';
  ctx.textAlign = 'center';
  ctx.textBaseline = 'middle';
  ctx.fillStyle = '#333';
  ctx.fillText(`${prozent}%`, 100, 100);
};

zeichneFortschritt(65);

Grad in Bogenmaß umrechnen

const ctx = document.querySelector('canvas').getContext('2d');
const rad = (grad) => (grad * Math.PI) / 180;

// Halbkreis oben (von 180° bis 360°)
ctx.beginPath();
ctx.arc(100, 100, 60, rad(180), rad(360));
ctx.stroke();

console.log(rad(90));

1.5707963267948966

// Wichtig · Fallstricke

Bogenmaß statt Grad: arc(x, y, r, 0, 360) ist ein häufiger Fehler. Umrechnen mit grad * Math.PI / 180.
Unerwünschte Verbindungslinie: Ohne beginPath() oder moveTo() verbindet arc() den letzten Pfadpunkt mit dem Bogenanfang. Bei mehreren Kreisen in einer Schleife entstehen so Striche zwischen ihnen. Vor jedem Kreis beginPath() aufrufen oder moveTo(x + r, y) setzen.
Negativer Radius wirft einen DOMException vom Typ IndexSizeError. Bei Animationen den Radius mit Math.max(0, r) absichern.
Winkelrichtung: Weil die y-Achse nach unten zeigt, ist „im Uhrzeigersinn“ die Standardrichtung. Der Winkel 0 liegt rechts, nicht oben. Für Uhren und Diagramme deshalb bei -Math.PI / 2 starten.
Für Ellipsen ellipse() verwenden. Für abgerundete Ecken zwischen zwei Linien ist arcTo() besser geeignet.
Die Methode gibt es auch bei Path2D und OffscreenCanvasRenderingContext2D. Sie wird von allen Browsern unterstützt.

Siehe auch

CanvasRenderingContext2D.arcTo() CanvasRenderingContext2D.rect() CanvasRenderingContext2D.save() CanvasRenderingContext2D.clip() CanvasRenderingContext2D.fill()