CanvasRenderingContext2D.fillText() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.fillText(text, x, y, maxWidth)

Beschreibung

fillText() ist die Standardmethode, um Text auf ein 2D-Canvas zu zeichnen, etwa für Beschriftungen in Diagrammen, Punktestände in Spielen, Wasserzeichen oder dynamisch erzeugte Grafiken. Der Text wird sofort als Pixel gerastert. Er lässt sich danach also weder markieren noch durchsuchen, und Screenreader können ihn nicht vorlesen.

Wie der Text aussieht, hängt vom aktuellen Zustand des Kontexts ab: font legt Schriftgröße und Schriftfamilie fest, fillStyle die Farbe, den Farbverlauf oder das Muster, textAlign die horizontale und textBaseline die vertikale Ausrichtung am Punkt (x, y), direction die Schreibrichtung. Auch shadow*, globalAlpha und die aktuelle Transformationsmatrix wirken sich aus.

Mit dem optionalen Parameter maxWidth begrenzt du die Breite: Ist der Text breiter, verkleinert der Browser die Schrift oder staucht sie horizontal zusammen. Einen automatischen Zeilenumbruch gibt es nicht. Mehrzeiligen Text musst du selbst aufteilen, am besten mit measureText(). Für umrandeten Text gibt es die Methode strokeText().

Parameter

Name	Typ	Beschreibung
$text Pflicht	string	Der Text, der gezeichnet werden soll. Andere Werte werden in einen String umgewandelt. Zeilenumbrüche (`\n`) werden wie Leerzeichen behandelt.
$x Pflicht	number	X-Koordinate des Ankerpunkts. Wie sie wirkt, hängt von `textAlign` ab.
$y Pflicht	number	Y-Koordinate des Ankerpunkts. Sie bezieht sich auf die mit `textBaseline` festgelegte Grundlinie (Standard: `alphabetic`).
$maxWidth	number	Maximale Breite in Pixeln. Ist der Text breiter, wird er verkleinert oder schmaler gesetzt. Bei `0`, negativen Werten oder `NaN` wird nichts gezeichnet.

Beispiele

Einfachen Text zeichnen

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

ctx.font = 'bold 32px system-ui, sans-serif';
ctx.fillStyle = '#1e40af';
ctx.fillText('Hallo Canvas!', 20, 50);

Zentrierte Beschriftung mit maxWidth

const ctx = document.querySelector('canvas').getContext('2d');
const { width, height } = ctx.canvas;

ctx.font = '48px Georgia, serif';
ctx.fillStyle = 'crimson';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';

// Genau in der Mitte, höchstens 80 % der Canvas-Breite
ctx.fillText('Ein ziemlich langer Titeltext', width / 2, height / 2, width * 0.8);

Mehrzeiliger Text mit eigenem Zeilenumbruch

const ctx = document.querySelector('canvas').getContext('2d');
ctx.font = '16px sans-serif';
ctx.fillStyle = '#222';
ctx.textBaseline = 'top';

const wrapText = (text, x, y, maxWidth, lineHeight) => {
  let line = '';
  for (const word of text.split(' ')) {
    const test = line ? `${line} ${word}` : word;
    if (ctx.measureText(test).width > maxWidth && line) {
      ctx.fillText(line, x, y);
      line = word;
      y += lineHeight;
    } else {
      line = test;
    }
  }
  ctx.fillText(line, x, y);
  return y + lineHeight; // nächste freie Zeile
};

const nextY = wrapText('Canvas bricht Text nicht automatisch um, deshalb messen wir jedes Wort selbst.', 10, 10, 200, 20);
console.log(nextY);

Y-Position der nächsten freien Zeile, z. B. 90 (hängt von Schrift und Browser ab)

Warten, bis eine Webfont geladen ist

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

const draw = async () => {
  // Ohne das Warten zeichnet der Browser eventuell mit der Ersatzschrift
  await document.fonts.load('24px "Roboto"');
  ctx.font = '24px "Roboto", sans-serif';
  ctx.fillStyle = 'black';
  ctx.fillText('Mit Webfont gezeichnet', 10, 40);
};

draw();

// Wichtig · Fallstricke

Kein automatischer Zeilenumbruch: \n erzeugt keine neue Zeile. Mehrzeiligen Text musst du selbst mit measureText() aufteilen.
Webfonts: Ist die Schrift beim Aufruf noch nicht geladen, zeichnet der Browser mit der Ersatzschrift und zeichnet später nicht neu. Warte vorher mit document.fonts.load() oder document.fonts.ready.
Unscharfer Text: Auf Bildschirmen mit hoher Pixeldichte wirkt Text verschwommen, wenn die Canvas-Auflösung nicht an devicePixelRatio angepasst ist. Setze canvas.width/canvas.height auf die CSS-Größe mal devicePixelRatio und rufe ctx.scale(devicePixelRatio, devicePixelRatio) auf.
Grundlinie: Standardmäßig ist y die alphabetische Grundlinie. Bei y = 0 liegt der Text deshalb fast vollständig außerhalb des sichtbaren Bereichs. Mit textBaseline = 'top' kannst du ihn oben ausrichten.
maxWidth: Bei 0, negativen Werten oder NaN wird gar nichts gezeichnet. Übergib den Parameter also nicht mit einem unkontrolliert berechneten Wert.
Barrierefreiheit: Canvas-Text ist für Screenreader unsichtbar. Wichtige Inhalte solltest du zusätzlich als Text im DOM, als Fallback-Inhalt im <canvas>-Element oder über ARIA-Attribute bereitstellen.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt, auch in OffscreenCanvasRenderingContext2D (etwa in Web Workers).

Siehe auch

CanvasRenderingContext2D.strokeText() CanvasRenderingContext2D.measureText() CanvasRenderingContext2D.font CanvasRenderingContext2D.fillStyle CanvasRenderingContext2D.textAlign CanvasRenderingContext2D.textBaseline CanvasRenderingContext2D