CanvasRenderingContext2D.wordSpacing — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.wordSpacing

Beschreibung

Die Eigenschaft wordSpacing des 2D-Kontexts legt fest, wie viel Abstand zwischen einzelnen Wörtern gezeichnet wird. Sie funktioniert wie die CSS-Eigenschaft word-spacing: Der angegebene Wert wird zum normalen Leerzeichen hinzugerechnet. Ein Wert von "0px" (Standard) bedeutet also normalen Abstand, positive Werte vergrößern ihn, negative verkleinern ihn.

Als Wert ist ein String mit einer CSS-Längenangabe erlaubt, z. B. "10px", "0.5em" oder "1rem". Prozentwerte werden nicht unterstützt. Ungültige Werte werden stillschweigend ignoriert, der vorherige Wert bleibt erhalten. Beim Auslesen bekommt man den Wert in der Form zurück, in der er gesetzt wurde (z. B. "0.5em").

Typische Einsatzfälle sind Blocksatz-ähnliche Layouts, Schlagzeilen mit großem Wortabstand, Beschriftungen in Diagrammen oder das Anpassen einer Textzeile an eine feste Breite. Die Einstellung wirkt sich auch auf measureText() aus. Wie alle Zeichenzustände wird sie von save() und restore() gesichert bzw. wiederhergestellt.

Parameter

Name	Typ	Default	Beschreibung
$value	string	"0px"	CSS-Längenangabe wie `"4px"`, `"0.25em"` oder `"-2px"`. Das ist der zusätzliche Abstand zwischen Wörtern. Prozentwerte und ungültige Strings werden ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wortabstand als CSS-Längen-String, z. B. "0px" oder "10px".

Beispiele

Wortabstand setzen und vergleichen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
ctx.font = '24px sans-serif';

console.log(ctx.wordSpacing);
ctx.fillText('Normaler Wortabstand', 10, 40);

ctx.wordSpacing = '20px';
ctx.fillText('Großer Wortabstand', 10, 90);
console.log(ctx.wordSpacing);

0px 20px

Text mit save()/restore() nur kurz aufweiten

const ctx = document.querySelector('canvas').getContext('2d');
ctx.font = 'bold 32px Georgia';

ctx.save();
ctx.wordSpacing = '0.5em';
ctx.fillText('JAHRES BILANZ 2024', 20, 50);
ctx.restore();

// Hier gilt wieder der Standardwert
ctx.fillText('Normaler Text', 20, 100);
console.log(ctx.wordSpacing);

0px

Zeile auf feste Breite ausrichten (einfacher Blocksatz)

const ctx = document.querySelector('canvas').getContext('2d');
ctx.font = '18px sans-serif';

const justifyLine = (text, x, y, targetWidth) => {
  const gaps = text.trim().split(/\s+/).length - 1;
  ctx.wordSpacing = '0px';
  const natural = ctx.measureText(text).width;
  if (gaps > 0 && natural < targetWidth) {
    ctx.wordSpacing = `${(targetWidth - natural) / gaps}px`;
  }
  ctx.fillText(text, x, y);
  ctx.wordSpacing = '0px';
};

justifyLine('Canvas kann jetzt auch Blocksatz', 10, 40, 380);

Funktion vorher prüfen

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

if ('wordSpacing' in ctx) {
  ctx.wordSpacing = '8px';
} else {
  console.warn('wordSpacing nicht unterstützt – Wörter einzeln zeichnen');
}

ctx.wordSpacing = '10%'; // ungültig, wird ignoriert
console.log(ctx.wordSpacing);

8px

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium ab Version 99, Safari ab 17 und Firefox ab 115 unterstützen die Eigenschaft. In älteren Browsern ist die Eigenschaft nicht vorhanden. Das Setzen bleibt dann ohne Wirkung und löst keinen Fehler aus. Deshalb vorher mit 'wordSpacing' in ctx prüfen.
Ungültige Werte (Zahlen ohne Einheit wie ctx.wordSpacing = 5, Prozentwerte, Tippfehler) werden stillschweigend ignoriert. Deshalb immer einen String mit Einheit angeben.
Relative Einheiten wie em beziehen sich auf die Schriftgröße, die gerade in ctx.font gesetzt ist. Bei rem wird die Schriftgröße des Canvas-Elements bzw. des Dokuments verwendet.
Als „Wort“ gilt Text, der durch Leerzeichen getrennt ist. Die Eigenschaft wirkt also nur an Wortgrenzen. Für den Abstand zwischen einzelnen Zeichen gibt es letterSpacing.
Das Zurücksetzen von canvas.width setzt auch wordSpacing auf "0px" zurück.
Auch in OffscreenCanvasRenderingContext2D verfügbar.

Siehe auch

CanvasRenderingContext2D.letterSpacing CanvasRenderingContext2D.font CanvasRenderingContext2D.fillText() CanvasRenderingContext2D.strokeText() CanvasRenderingContext2D.measureText() CanvasRenderingContext2D