Signatur
Beschreibung
Die Eigenschaft lineDashOffset des 2D-Canvas-Kontexts bestimmt, an welcher Stelle das Strichmuster einer gestrichelten Linie beginnt. Das Muster selbst wird mit setLineDash() festgelegt; lineDashOffset verschiebt es entlang des Pfades. Standardwert ist 0.0.
Ein positiver Wert verschiebt das Muster rückwärts, also in Richtung Pfadanfang: Der Strich scheint „nach hinten“ zu wandern. Ein negativer Wert verschiebt es in Zeichenrichtung nach vorn. Der Versatz wird in Einheiten des Koordinatensystems angegeben und ist damit von der aktuellen Transformation (z. B. scale()) abhängig.
Typischer Einsatzzweck ist der sogenannte „Marching Ants“-Effekt – ein animierter, laufender Auswahlrahmen, wie man ihn aus Bildbearbeitungsprogrammen kennt. Außerdem lässt sich damit ein Strichmuster exakt an Ecken oder Startpunkten ausrichten, oder ein „Zeichnen“-Effekt für Linien animieren.
Die Eigenschaft wirkt nur auf Konturen, also auf stroke(), strokeRect() und strokeText() – nicht auf Füllungen. Sie gehört zum Zeichenzustand und wird von save()/restore() gesichert bzw. wiederhergestellt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | 0 | Versatz des Strichmusters in Koordinateneinheiten (Gleitkommazahl). Infinity, -Infinity und NaN werden ignoriert. |
Rückgabewert
0.Beispiele
Strichmuster mit und ohne Versatz vergleichen
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
ctx.setLineDash([20, 10]);
ctx.lineWidth = 4;
// Ohne Versatz
ctx.beginPath();
ctx.moveTo(10, 30);
ctx.lineTo(300, 30);
ctx.stroke();
// Mit Versatz: Muster beginnt 10 Einheiten später im Zyklus
ctx.lineDashOffset = 10;
ctx.strokeStyle = 'crimson';
ctx.beginPath();
ctx.moveTo(10, 60);
ctx.lineTo(300, 60);
ctx.stroke();
console.log(ctx.lineDashOffset);„Marching Ants“ – animierter Auswahlrahmen
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
let offset = 0;
const draw = () => {
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.setLineDash([6, 4]);
ctx.lineDashOffset = -offset; // negativ = Muster läuft vorwärts
ctx.strokeRect(20, 20, 200, 120);
};
const tick = () => {
offset = (offset + 0.5) % 10; // 10 = Summe des Musters (6 + 4)
draw();
requestAnimationFrame(tick);
};
requestAnimationFrame(tick);Linie „zeichnen“ lassen (Draw-on-Effekt)
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const length = 400; // Länge der Linie
let progress = 0;
const animate = () => {
ctx.clearRect(0, 0, canvas.width, canvas.height);
// Ein Strich und eine Lücke, jeweils so lang wie die Linie
ctx.setLineDash([length, length]);
ctx.lineDashOffset = length - progress;
ctx.lineWidth = 3;
ctx.beginPath();
ctx.moveTo(20, 100);
ctx.lineTo(20 + length, 100);
ctx.stroke();
if (progress < length) {
progress += 4;
requestAnimationFrame(animate);
}
};
animate();// Wichtig · Fallstricke
- Ohne Strichmuster keine Wirkung: Solange
setLineDash()nicht mit einem nicht-leeren Array aufgerufen wurde, hatlineDashOffsetkeinen sichtbaren Effekt. - Richtung beachten: Positive Werte verschieben das Muster zum Pfadanfang hin, negative in Zeichenrichtung – bei Animationen wirkt das oft „falsch herum“.
- Ungültige Werte:
NaNund±Infinitywerden stillschweigend ignoriert, es wird kein Fehler geworfen. - Wertüberlauf bei Animationen: Den Versatz per Modulo auf die Musterlänge (Summe der Array-Einträge von
setLineDash()) begrenzen, damit die Zahl nicht unbegrenzt wächst und Genauigkeit verliert. - Transformationen: Der Versatz wird in lokalen Koordinaten interpretiert; nach
scale()verändert sich die sichtbare Verschiebung entsprechend. - Kompatibilität: In allen modernen Browsern sowie in
OffscreenCanvasRenderingContext2Dverfügbar. Internet Explorer unterstützt es erst ab Version 11.