CanvasRenderingContext2D.setLineDash() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.setLineDash(segments)

Beschreibung

setLineDash() bestimmt, ob Linien auf einem 2D-Canvas durchgezogen, gestrichelt oder gepunktet gezeichnet werden. Übergeben wird ein Array von Zahlen, die abwechselnd die Länge eines sichtbaren Strichs und einer Lücke angeben – gemessen in Einheiten des aktuellen Koordinatensystems (also von scale() und anderen Transformationen beeinflusst).

Ist die Anzahl der Elemente ungerade, wird das Array intern verdoppelt: [5, 10, 15] wird zu [5, 10, 15, 5, 10, 15]. Ein leeres Array [] stellt wieder durchgezogene Linien her. Das Muster gilt für alle nachfolgenden Strich-Operationen, bis es erneut geändert oder per restore() zurückgesetzt wird.

Typische Einsatzgebiete sind Hilfslinien in Diagrammen, Auswahlrahmen („Marching Ants“ in Kombination mit lineDashOffset), Markierungen in Karten oder Editor-Oberflächen. Das aktuelle Muster lässt sich mit getLineDash() auslesen.

Parameter

Name	Typ	Default	Beschreibung
$segments Pflicht	number[]		Array aus nicht-negativen, endlichen Zahlen: abwechselnd Strich- und Lückenlänge. `[]` setzt auf durchgezogene Linie zurück. Enthält das Array negative Werte, `NaN` oder `Infinity`, wird der Aufruf still ignoriert.

Beispiele

Gestrichelte und gepunktete Linien

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

// Gestrichelt: 10px Strich, 5px Lücke
ctx.setLineDash([10, 5]);
ctx.beginPath();
ctx.moveTo(20, 30);
ctx.lineTo(280, 30);
ctx.stroke();

// Gepunktet: runde Kappen + Strichlänge 0
ctx.lineCap = 'round';
ctx.setLineDash([0, 8]);
ctx.beginPath();
ctx.moveTo(20, 60);
ctx.lineTo(280, 60);
ctx.stroke();

// Zurück zur durchgezogenen Linie
ctx.setLineDash([]);
ctx.lineCap = 'butt';
ctx.beginPath();
ctx.moveTo(20, 90);
ctx.lineTo(280, 90);
ctx.stroke();

Ungerade Anzahl von Segmenten

const ctx = document.createElement('canvas').getContext('2d');
ctx.setLineDash([5, 10, 15]);
console.log(ctx.getLineDash());

[5, 10, 15, 5, 10, 15]

Animierter Auswahlrahmen (Marching Ants)

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

const draw = () => {
  ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
  ctx.save();
  ctx.setLineDash([6, 4]);
  ctx.lineDashOffset = -offset;
  ctx.strokeStyle = '#333';
  ctx.strokeRect(20, 20, 200, 120);
  ctx.restore(); // Muster gilt nur innerhalb von save/restore

  offset = (offset + 0.5) % 10;
  requestAnimationFrame(draw);
};

requestAnimationFrame(draw);

Hilfslinien in einem Diagramm

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

ctx.save();
ctx.strokeStyle = '#ccc';
ctx.setLineDash([4, 4]);
for (let y = 50; y <= 250; y += 50) {
  ctx.beginPath();
  ctx.moveTo(0, y + 0.5); // +0.5 für scharfe 1px-Linien
  ctx.lineTo(width, y + 0.5);
  ctx.stroke();
}
ctx.restore();

// Wichtig · Fallstricke

Ungültige Werte werden still ignoriert: Negative Zahlen, NaN oder Infinity lösen keinen Fehler aus – das alte Muster bleibt einfach bestehen. Werte daher vorher prüfen.
Kein Einfluss auf Füllungen: Das Muster wirkt nur bei stroke(), strokeRect() und strokeText(), nicht bei fill().
Zustand ist „klebrig“: Das Muster bleibt für alle folgenden Linien aktiv. Mit save()/restore() einkapseln oder mit setLineDash([]) zurücksetzen.
Transformationen: Längen werden im aktuellen Koordinatensystem interpretiert – ein scale(2, 2) verdoppelt auch die Strichlängen.
lineCap beachten: Bei 'round' oder 'square' ragt jeder Strich um die halbe Linienbreite über seine Länge hinaus; die Lücken wirken dadurch kleiner.
Kompatibilität: In allen modernen Browsern verfügbar, ebenso in OffscreenCanvasRenderingContext2D und bei Path2D-Pfaden. Sehr alte Browser (IE ≤ 10) kennen die Methode nicht.

Siehe auch

CanvasRenderingContext2D.getLineDash() CanvasRenderingContext2D.lineDashOffset CanvasRenderingContext2D.lineCap CanvasRenderingContext2D.lineWidth CanvasRenderingContext2D.stroke() CanvasRenderingContext2D