TextMetrics.actualBoundingBoxLeft — Eigenschaft · JavaScript-Referenz

Signatur

TextMetrics.actualBoundingBoxLeft

Beschreibung

actualBoundingBoxLeft ist eine schreibgeschützte Eigenschaft des TextMetrics-Objekts, das CanvasRenderingContext2D.measureText() zurückgibt. Der Wert (ein double) gibt den Abstand parallel zur Grundlinie an: vom Ausrichtungspunkt, den textAlign festlegt, bis zur linken Kante des Rechtecks, das die tatsächlich gezeichneten Glyphen umschließt.

Positive Werte bedeuten, dass der Rahmen links vom Ausrichtungspunkt beginnt. Bei textAlign = "left" oder "start" (in LTR) ist der Wert meist 0 oder ganz klein, bei manchen Glyphen (z. B. kursiv oder mit Überhang wie „j“) auch negativ. Bei "center" liegt er ungefähr bei der halben Breite, bei "right" ungefähr bei der ganzen.

Zusammen mit actualBoundingBoxRight, actualBoundingBoxAscent und actualBoundingBoxDescent bekommst du den pixelgenauen Begrenzungsrahmen des Textes. Den brauchst du etwa für enge Hintergrundflächen, Treffertests, Text-Hervorhebungen oder genaues Zentrieren. Anders als width, das die Vorschubbreite (Advance Width) liefert, beschreibt dieser Wert die tatsächliche Ausdehnung der Tinte.

Die Breite des sichtbaren Rahmens berechnest du mit actualBoundingBoxLeft + actualBoundingBoxRight. Die linke Kante in Canvas-Koordinaten liegt bei x - actualBoundingBoxLeft.

Rückgabewert

Typ

number

Beschreibung

Ein Gleitkommawert in CSS-Pixeln. Positiv heißt: Die linke Kante des Rahmens liegt links vom Ausrichtungspunkt. Negativ heißt: Sie liegt rechts davon.

Beispiele

Wert auslesen

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

const metrics = ctx.measureText('Hallo Welt');
console.log(metrics.actualBoundingBoxLeft);  // meist ~0 bei textAlign 'start'
console.log(metrics.actualBoundingBoxRight); // ungefähr die sichtbare Breite

0 151.3 (Wert hängt von Schrift und Browser ab)

Einfluss von textAlign

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

for (const align of ['left', 'center', 'right']) {
  ctx.textAlign = align;
  const { actualBoundingBoxLeft } = ctx.measureText('Canvas');
  console.log(align, actualBoundingBoxLeft.toFixed(1));
}

left 0.0 center 61.2 right 122.4 (Werte ungefähr, je nach Schrift)

Eng anliegenden Hintergrund hinter zentrierten Text zeichnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
ctx.font = 'bold 36px system-ui';
ctx.textAlign = 'center';
ctx.textBaseline = 'alphabetic';

const text = 'Angebot!';
const x = canvas.width / 2;
const y = 80;
const m = ctx.measureText(text);

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

ctx.fillStyle = '#ffd54f';
ctx.fillRect(left - pad, top - pad, width + pad * 2, height + pad * 2);
ctx.fillStyle = '#222';
ctx.fillText(text, x, y);

// Wichtig · Fallstricke

Vorzeichen beachten: Positive Werte zeigen nach links. Die linke Kante ist also x - actualBoundingBoxLeft, nicht x + ….
Der Wert hängt von font, textAlign und direction ab, und zwar vom Zustand zum Zeitpunkt von measureText(). Änderst du diese Einstellungen später, stimmen alte Messwerte nicht mehr.
Bei direction = "rtl" bezieht sich "start" auf die rechte Seite, der Wert fällt dann entsprechend groß aus.
actualBoundingBoxLeft + actualBoundingBoxRight ist meist nicht dasselbe wie width, weil width die Vorschubbreite inklusive Seitenabständen der Glyphen misst.
Web-Fonts müssen geladen sein, bevor du misst (z. B. mit await document.fonts.ready). Sonst misst der Browser die Ersatzschrift.
Die Werte unterscheiden sich leicht zwischen Browsern und Betriebssystemen (Rendering, Hinting) und können auf Pixelbruchteile gerundet sein.
Kompatibilität: Chrome 77+, Firefox 74+, Safari 11.1+. Die Eigenschaft ist auch in OffscreenCanvasRenderingContext2D verfügbar, also in Workern.

Siehe auch

TextMetrics.actualBoundingBoxAscent TextMetrics.actualBoundingBoxRight TextMetrics.actualBoundingBoxDescent TextMetrics.fontBoundingBoxAscent TextMetrics.fontBoundingBoxDescent