CanvasRenderingContext2D.letterSpacing — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.letterSpacing

Beschreibung

Die Eigenschaft letterSpacing des 2D-Kontexts bestimmt, wie viel zusätzlicher Abstand zwischen einzelnen Zeichen eingefügt wird, wenn Text mit fillText() oder strokeText() gezeichnet wird. Sie arbeitet wie die CSS-Eigenschaft letter-spacing und nimmt eine Zeichenkette mit einer CSS-Längenangabe entgegen, z. B. "3px", "0.1em" oder "-1px". Der Standardwert ist "0px".

Typische Einsatzfälle sind gesperrte Überschriften, Logos und Beschriftungen in Diagrammen oder Spielen. Außerdem hilft die Eigenschaft, Text-Layouts aus HTML/CSS genau auf dem Canvas nachzubauen. Negative Werte rücken die Zeichen enger zusammen.

Wichtig: Der Wert wirkt sich auch auf measureText() aus. Die gemessene Breite enthält also den zusätzlichen Abstand. Wie alle Zustandseigenschaften des Kontexts wird letterSpacing mit save() gesichert und mit restore() wiederhergestellt. Relative Einheiten wie em beziehen sich auf die Schriftgröße, die in ctx.font gerade gesetzt ist.

Parameter

Name	Typ	Default	Beschreibung
$value	string	"0px"	CSS-Längenangabe (`px`, `em`, `rem`, `pt` …), auch negativ. Prozentangaben und ungültige Werte werden stillschweigend ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Buchstabenabstand als Zeichenkette, z. B. "0px" oder "0.2em".

Beispiele

Gesperrte Überschrift zeichnen

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

ctx.font = 'bold 32px sans-serif';
ctx.fillText('NORMAL', 10, 50);

ctx.letterSpacing = '8px';
ctx.fillText('GESPERRT', 10, 100);

console.log(ctx.letterSpacing);

8px

Auswirkung auf measureText() und Zentrieren

const ctx = document.createElement('canvas').getContext('2d');
ctx.font = '20px Arial';

const ohne = ctx.measureText('Hallo').width;
ctx.letterSpacing = '5px';
const mit = ctx.measureText('Hallo').width;

console.log(mit > ohne); // Abstand fließt in die Breite ein

// Text horizontal zentrieren
const x = (ctx.canvas.width - mit) / 2;
ctx.fillText('Hallo', x, 40);

true

Zustand mit save()/restore() kapseln und Unterstützung prüfen

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

const drawLabel = (text, x, y, spacing = '0.15em') => {
  ctx.save();
  ctx.font = '600 14px system-ui';
  if (unterstuetzt) ctx.letterSpacing = spacing;
  ctx.fillText(text.toUpperCase(), x, y);
  ctx.restore();
};

drawLabel('Umsatz 2024', 20, 30);
console.log(ctx.letterSpacing);

0px

Ungültige Werte werden ignoriert

const ctx = document.createElement('canvas').getContext('2d');
ctx.letterSpacing = '4px';
ctx.letterSpacing = '10%';   // ungültig
ctx.letterSpacing = 'weit';  // ungültig
console.log(ctx.letterSpacing);

4px

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen die Eigenschaft ab Version 99, Firefox ab 115, Safari erst ab 18.4. Prüfe die Unterstützung mit 'letterSpacing' in ctx. In älteren Browsern hat das Setzen keine Wirkung. Als Ausweichlösung zeichnest du jedes Zeichen einzeln und rückst dabei selbst weiter.
Nur Zeichenketten: Eine Zahl wie ctx.letterSpacing = 5 ist keine gültige CSS-Länge und wird ignoriert. Die Einheit ist Pflicht, also "5px".
Prozentwerte sind nicht erlaubt, anders als bei manchen CSS-Kontexten.
Auch hinter dem letzten Zeichen wird Abstand eingefügt. Das kann bei textAlign = 'center' oder 'right' zu einer leichten Verschiebung führen.
em-Werte werden beim Setzen anhand der aktuellen font berechnet. Setze deshalb zuerst font und danach letterSpacing.
Die Eigenschaft gibt es auch in OffscreenCanvasRenderingContext2D, also in Web Workern.

Siehe auch

CanvasRenderingContext2D.wordSpacing CanvasRenderingContext2D.font CanvasRenderingContext2D.fillText() CanvasRenderingContext2D.measureText() CanvasRenderingContext2D.fontKerning CanvasRenderingContext2D