TextMetrics.actualBoundingBoxDescent — Eigenschaft · JavaScript-Referenz

Signatur

TextMetrics.actualBoundingBoxDescent

Beschreibung

Die schreibgeschützte Eigenschaft actualBoundingBoxDescent eines TextMetrics-Objekts gibt als double an, wie weit der tatsächlich gezeichnete Text unter die horizontale Linie reicht, die über CanvasRenderingContext2D.textBaseline festgelegt ist. Ein positiver Wert bedeutet, dass Glyphen unter diese Linie reichen. Das ist typisch für Unterlängen wie bei g, p oder y.

Anders als fontBoundingBoxDescent, das sich auf die Metriken der ganzen Schrift bezieht, beschreibt actualBoundingBoxDescent nur die konkret gemessenen Zeichen. Bei "Hallo" ist der Wert mit der Grundlinie alphabetic daher etwa 0, bei "Hying" dagegen deutlich größer.

Zusammen mit actualBoundingBoxAscent ergibt sich die sichtbare Höhe des Textes: ascent + descent. Das braucht man, um Text pixelgenau vertikal zu zentrieren, enge Hintergründe oder Markierungen zu zeichnen oder Kollisionen in Diagrammen und Spielen zu prüfen.

Rückgabewert

Typ

number

Beschreibung

Abstand in CSS-Pixeln von der textBaseline-Linie bis zur Unterkante des tatsächlichen Begrenzungsrahmens. Positive Werte liegen unterhalb der Linie, negative oberhalb.

Beispiele

Unterlänge verschiedener Texte vergleichen

const ctx = document.createElement('canvas').getContext('2d');
ctx.font = '32px sans-serif';
ctx.textBaseline = 'alphabetic';

for (const text of ['Hallo', 'Typografie']) {
  const m = ctx.measureText(text);
  console.log(text, m.actualBoundingBoxDescent.toFixed(1));
}

Hallo 0.3 Typografie 7.0 (Werte hängen von Schrift und Browser ab)

Enger Hintergrund hinter einem Text

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

const text = 'Jugendstil';
const x = 20, y = 80;
const m = ctx.measureText(text);

const top = y - m.actualBoundingBoxAscent;
const height = m.actualBoundingBoxAscent + m.actualBoundingBoxDescent;
const left = x - m.actualBoundingBoxLeft;
const width = m.actualBoundingBoxLeft + m.actualBoundingBoxRight;

ctx.fillStyle = '#ffe08a';
ctx.fillRect(left, top, width, height);
ctx.fillStyle = '#222';
ctx.fillText(text, x, y);

Text pixelgenau vertikal zentrieren

const drawCentered = (ctx, text, cx, cy) => {
  ctx.textBaseline = 'alphabetic';
  ctx.textAlign = 'center';
  const m = ctx.measureText(text);
  const inkHeight = m.actualBoundingBoxAscent + m.actualBoundingBoxDescent;
  // Grundlinie so verschieben, dass die sichtbare Tinte mittig sitzt
  const baselineY = cy + inkHeight / 2 - m.actualBoundingBoxDescent;
  ctx.fillText(text, cx, baselineY);
};

const ctx = document.querySelector('canvas').getContext('2d');
ctx.font = '28px sans-serif';
drawCentered(ctx, 'Qypg', 150, 75);

// Wichtig · Fallstricke

Der Wert hängt vom aktuellen textBaseline und font zum Zeitpunkt von measureText() ab. Wer diese Eigenschaften danach ändert, muss neu messen.
Das Vorzeichen kann negativ werden, etwa bei textBaseline = 'bottom' oder bei Text ganz ohne Unterlängen wie "—".
Wird eine Webfont noch geladen, misst der Browser die Ersatzschrift. Vorher auf document.fonts.ready warten.
Die Werte unterscheiden sich je nach Browser und Betriebssystem, weil Schriften unterschiedlich gerastert werden, und enthalten Nachkommastellen. Für Pixelraster gegebenenfalls runden.
Unterstützt in Chrome/Edge 77+, Firefox 74+ und Safari 11.1+. In älteren Browsern ist der Wert undefined, deshalb bei Bedarf mit einem Ersatzwert absichern, z. B. m.actualBoundingBoxDescent ?? 0.
Funktioniert auch mit OffscreenCanvasRenderingContext2D in Web Workern.

Siehe auch

TextMetrics TextMetrics.actualBoundingBoxAscent TextMetrics.fontBoundingBoxDescent CanvasRenderingContext2D.measureText() CanvasRenderingContext2D.textBaseline TextMetrics.width