CanvasRenderingContext2D.textBaseline — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.textBaseline

Beschreibung

Die Eigenschaft textBaseline bestimmt, wie die y-Koordinate interpretiert wird, die an fillText(), strokeText() und measureText() übergeben wird. Standardmäßig ist der Wert "alphabetic". Die y-Koordinate liegt dann auf der Linie, auf der lateinische Buchstaben „stehen“. Unterlängen wie bei „g“ oder „p“ ragen darunter hinaus.

Mögliche Werte:

"top": Die y-Koordinate liegt an der Oberkante des em-Quadrats.
"hanging": Hängende Basislinie, z. B. für Devanagari oder Tibetisch.
"middle": Die y-Koordinate liegt in der Mitte des em-Quadrats.
"alphabetic": Normale alphabetische Basislinie (Standardwert).
"ideographic": Ideografische Basislinie für chinesische, japanische und koreanische Schrift (CJK). Sie liegt unterhalb der Unterlängen.
"bottom": Die y-Koordinate liegt an der Unterkante des em-Quadrats.

In der Praxis ist textBaseline vor allem nützlich, um Text exakt zu positionieren. Beispiele sind Beschriftungen in Diagrammen, zentrierter Text in Buttons oder Kreisen und Text, der oben links an einem Rahmen ausgerichtet ist. Zusammen mit textAlign lässt sich Text horizontal und vertikal um einen Punkt zentrieren.

Die Eigenschaft gehört zum Zeichenzustand des Kontexts. Sie wird also mit save() gesichert und mit restore() wiederhergestellt.

Parameter

Name	Typ	Default	Beschreibung
$value	"top" \| "hanging" \| "middle" \| "alphabetic" \| "ideographic" \| "bottom"	"alphabetic"	Neuer Wert der Basislinie. Ungültige Zeichenketten werden ohne Fehlermeldung ignoriert, der bisherige Wert bleibt erhalten.

Rückgabewert

Typ

string

Beschreibung

Die aktuell eingestellte Basislinie als Zeichenkette, z. B. "alphabetic".

Beispiele

Alle Basislinien im Vergleich

const canvas = document.querySelector('canvas');
canvas.width = 700;
canvas.height = 120;
const ctx = canvas.getContext('2d');

const baselines = ['top', 'hanging', 'middle', 'alphabetic', 'ideographic', 'bottom'];
ctx.font = '20px sans-serif';

// Hilfslinie bei y = 60
ctx.strokeStyle = 'red';
ctx.beginPath();
ctx.moveTo(0, 60);
ctx.lineTo(canvas.width, 60);
ctx.stroke();

baselines.forEach((baseline, i) => {
  ctx.textBaseline = baseline;
  ctx.fillText(`Ag ${baseline}`, 10 + i * 115, 60);
});

Text in einem Kreis zentrieren

const ctx = document.querySelector('canvas').getContext('2d');
const cx = 100, cy = 100, r = 50;

ctx.fillStyle = '#2563eb';
ctx.beginPath();
ctx.arc(cx, cy, r, 0, Math.PI * 2);
ctx.fill();

ctx.fillStyle = '#fff';
ctx.font = 'bold 32px sans-serif';
ctx.textAlign = 'center';    // horizontal zentrieren
ctx.textBaseline = 'middle'; // vertikal zentrieren
ctx.fillText('42', cx, cy);

Text oben links in einem Rahmen positionieren

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

ctx.strokeRect(20, 20, 200, 80);

ctx.save();
ctx.font = '16px system-ui';
ctx.textBaseline = 'top'; // y ist jetzt die Oberkante des Textes
ctx.fillText('Umsatz Q3', 20 + padding, 20 + padding);
ctx.restore();

console.log(ctx.textBaseline);

alphabetic

Ungültige Werte werden ignoriert

const ctx = document.createElement('canvas').getContext('2d');
ctx.textBaseline = 'middle';
ctx.textBaseline = 'center'; // kein gültiger Wert
console.log(ctx.textBaseline);

middle

// Wichtig · Fallstricke

Der Wert "center" gibt es nicht: Vertikal heißt der Wert "middle". Tippfehler oder "center" werden ohne Fehlermeldung ignoriert. Dann bleibt die alte Einstellung aktiv.
"middle" bezieht sich auf die Mitte des em-Quadrats und nicht auf die sichtbaren Glyphen. Text aus Großbuchstaben oder Ziffern kann deshalb leicht verschoben wirken. Für pixelgenaue Zentrierung eignen sich measureText() mit actualBoundingBoxAscent und actualBoundingBoxDescent.
Die Darstellung von "hanging" und "ideographic" hängt von der Schriftart ab. Sie kann sich zwischen Browsern und Betriebssystemen unterscheiden, besonders wenn die Schrift keine passenden Metriken enthält.
Die Eigenschaft beeinflusst auch die Werte, die measureText() zurückgibt (z. B. actualBoundingBoxAscent), weil diese relativ zur eingestellten Basislinie berechnet werden.
Wird die Canvas-Größe geändert (width/height), setzt der Browser den gesamten Kontext zurück. textBaseline ist danach wieder "alphabetic".
Die Eigenschaft wird von allen modernen Browsern unterstützt, auch von OffscreenCanvasRenderingContext2D.

Siehe auch

CanvasRenderingContext2D.textAlign CanvasRenderingContext2D.font CanvasRenderingContext2D.fillText() CanvasRenderingContext2D.strokeText() CanvasRenderingContext2D.measureText() CanvasRenderingContext2D.direction CanvasRenderingContext2D