CanvasRenderingContext2D.getLineDash() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.getLineDash()

Beschreibung

Mit getLineDash() liest du das Strichelmuster aus, das der Canvas-2D-Kontext beim Zeichnen von Linien und Umrissen verwendet (z. B. bei stroke(), strokeRect() oder strokeText()). Das Muster ist ein Array aus Zahlen, die abwechselnd die Länge eines gezeichneten Strichs und der folgenden Lücke angeben. Die Werte gelten in Einheiten des Koordinatenraums, also vor der aktuellen Transformation.

Ist kein Muster gesetzt, gibt die Methode ein leeres Array zurück. Das bedeutet: durchgezogene Linie. Hat man setLineDash() mit einer ungeraden Anzahl an Werten aufgerufen, wird die Liste intern verdoppelt, damit sich eine gerade Anzahl ergibt. Aus [5, 15, 25] wird dann [5, 15, 25, 5, 15, 25]. Genau diese verdoppelte Form liefert getLineDash() auch zurück.

Typische Einsätze sind das Sichern und Wiederherstellen eines Musters innerhalb einer Zeichenfunktion, das Umschalten zwischen gestrichelt und durchgezogen (z. B. bei Auswahlrahmen oder Hilfslinien) und das Debugging von Zeichenzuständen. Das Strichelmuster gehört zum Zeichenzustand und wird deshalb auch von save() und restore() erfasst.

Rückgabewert

Typ

number[]

Beschreibung

Ein neues Array aus nicht-negativen Zahlen mit abwechselnden Strich- und Lückenlängen. Die Anzahl der Einträge ist immer gerade. Ist kein Muster gesetzt, ist das Array leer ([]).

Beispiele

Muster setzen und auslesen

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

console.log(ctx.getLineDash()); // Standard: durchgezogen

ctx.setLineDash([10, 5]);
console.log(ctx.getLineDash());

ctx.beginPath();
ctx.moveTo(20, 50);
ctx.lineTo(280, 50);
ctx.stroke();

[] [10, 5]

Ungerade Anzahl wird verdoppelt

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

ctx.setLineDash([5, 15, 25]);
console.log(ctx.getLineDash());
console.log(ctx.getLineDash().length);

[5, 15, 25, 5, 15, 25] 6

Muster in einer Hilfsfunktion sichern und wiederherstellen

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

// Zeichnet einen gestrichelten Auswahlrahmen, ohne das bestehende Muster zu verändern
const drawSelection = (x, y, w, h) => {
  const previous = ctx.getLineDash();
  ctx.setLineDash([4, 4]);
  ctx.strokeRect(x, y, w, h);
  ctx.setLineDash(previous);
};

ctx.setLineDash([12, 3]);
drawSelection(10, 10, 100, 60);
console.log(ctx.getLineDash());

[12, 3]

Zurückgegebenes Array ist eine Kopie

const ctx = document.createElement('canvas').getContext('2d');
ctx.setLineDash([8, 4]);

const dash = ctx.getLineDash();
dash.push(2, 2); // ändert nur die Kopie

console.log(ctx.getLineDash());

// Änderungen erst durch erneutes Setzen übernehmen
ctx.setLineDash(dash);
console.log(ctx.getLineDash());

[8, 4] [8, 4, 2, 2]

// Wichtig · Fallstricke

Kopie statt Referenz: Jeder Aufruf gibt ein neues Array zurück. Wenn du es veränderst, wirkt sich das nicht auf den Kontext aus. Übernimm Änderungen mit setLineDash().
Verdopplung: Bei einer ungeraden Anzahl an Werten ist das Ergebnis nicht identisch mit der Eingabe von setLineDash(). Vergleiche mit der Originaleingabe (z. B. in Tests) schlagen deshalb fehl.
Ungültige Werte: Enthält die Eingabe von setLineDash() negative Werte, NaN oder Infinity, wird der Aufruf still ignoriert. getLineDash() liefert dann weiterhin das vorherige Muster.
Versatz nicht enthalten: Der Startversatz des Musters steckt nicht im Rückgabewert. Er steht in der Eigenschaft lineDashOffset.
Zeichenzustand: save() und restore() sichern das Muster mit. Ein Zurücksetzen des Canvas (z. B. durch Ändern von canvas.width) setzt es wieder auf [].
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt, auch von Internet Explorer 11. Sie steht auch in OffscreenCanvasRenderingContext2D zur Verfügung, also in Web Workern.

Siehe auch

CanvasRenderingContext2D.setLineDash() CanvasRenderingContext2D.lineDashOffset CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.save() CanvasRenderingContext2D CanvasRenderingContext2D.drawFocusIfNeeded()