CanvasRenderingContext2D.lineWidth — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.lineWidth

Beschreibung

Die Eigenschaft lineWidth des 2D-Kontexts bestimmt die Strichstärke aller Kontur-Operationen, also stroke(), strokeRect() und strokeText(). Der Wert ist eine Zahl in Einheiten des aktuellen Koordinatenraums. Der Standardwert ist 1.0.

Die Linie wird mittig auf dem Pfad gezeichnet, d. h. jeweils die Hälfte der Breite liegt auf jeder Seite des Pfads. Deshalb wirkt eine 1 Pixel breite Linie auf ganzzahligen Koordinaten oft unscharf und grau: Sie verteilt sich auf zwei Pixelreihen. Abhilfe schafft ein Versatz um 0.5 Pixel.

Der Wert gehört zum Zeichenzustand und wird mit save() gesichert bzw. mit restore() wiederhergestellt. Er wird außerdem von der aktuellen Transformationsmatrix beeinflusst: Nach scale(2, 2) erscheint eine Linie mit lineWidth = 1 auf dem Bildschirm 2 Pixel breit.

Wichtig: Maßgeblich ist der Wert zum Zeitpunkt des Aufrufs von stroke(), nicht der Wert beim Anlegen des Pfads. Wer mehrere Linien mit unterschiedlicher Stärke braucht, muss für jede einen eigenen Pfad mit beginPath() beginnen.

Parameter

Name	Typ	Default	Beschreibung
$value	number	1	Neue Linienbreite in Einheiten des Koordinatenraums. Nur endliche Werte größer als `0` werden übernommen.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Linienbreite. Standardwert ist 1.

Beispiele

Linien mit unterschiedlicher Stärke zeichnen

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

[1, 4, 8, 16].forEach((width, i) => {
  ctx.beginPath();          // eigener Pfad je Linie!
  ctx.lineWidth = width;
  ctx.moveTo(20, 30 + i * 30);
  ctx.lineTo(280, 30 + i * 30);
  ctx.stroke();
});

console.log(ctx.lineWidth);

16

Scharfe 1-Pixel-Linien durch 0,5-Versatz

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

// unscharf: Linie liegt genau auf der Pixelgrenze
ctx.beginPath();
ctx.moveTo(10, 20);
ctx.lineTo(200, 20);
ctx.stroke();

// scharf: Linie liegt in der Pixelmitte
ctx.beginPath();
ctx.moveTo(10, 40.5);
ctx.lineTo(200, 40.5);
ctx.stroke();

Ungültige Werte werden ignoriert

const ctx = document.createElement('canvas').getContext('2d');
ctx.lineWidth = 5;
ctx.lineWidth = 0;        // ignoriert
ctx.lineWidth = -3;       // ignoriert
ctx.lineWidth = NaN;      // ignoriert
ctx.lineWidth = Infinity; // ignoriert
console.log(ctx.lineWidth);

ctx.lineWidth = '2.5';    // wird zu Zahl umgewandelt
console.log(ctx.lineWidth);

5 2.5

Zustand mit save()/restore() und Einfluss von scale()

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

ctx.save();
ctx.scale(3, 3);
ctx.strokeRect(10, 10, 40, 40); // wirkt 6 px breit
ctx.lineWidth = 0.5;
ctx.strokeRect(60, 10, 40, 40); // wirkt 1,5 px breit
ctx.restore();

console.log(ctx.lineWidth);

2

// Wichtig · Fallstricke

Ungültige Werte: 0, negative Zahlen, NaN und Infinity werden stillschweigend ignoriert. Es wird kein Fehler geworfen, der alte Wert bleibt erhalten.
Pfad nicht vergessen: Ohne beginPath() zeichnet ein späteres stroke() alle vorherigen Segmente erneut, und zwar mit der aktuellen Breite.
HiDPI/Retina: Wird das Canvas für devicePixelRatio hochskaliert (z. B. mit ctx.scale(dpr, dpr)), skaliert auch die Linienbreite mit. Wie groß der 0,5-Versatz sein muss, hängt dann von diesem Faktor ab.
Ecken und Enden: Bei dicken Linien fallen lineJoin, lineCap und miterLimit deutlich auf. Spitze Winkel mit lineJoin = 'miter' können weit über den Pfad hinausragen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in OffscreenCanvasRenderingContext2D und in Web Workern.

Siehe auch

CanvasRenderingContext2D.lineCap CanvasRenderingContext2D.lineJoin CanvasRenderingContext2D.miterLimit CanvasRenderingContext2D.setLineDash() CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.strokeStyle CanvasRenderingContext2D