SVGTextContentElement.getSubStringLength() — Methode · JavaScript-Referenz

Signatur

SVGTextContentElement.prototype.getSubStringLength(charnum, nchars)

Beschreibung

Die Methode getSubStringLength() misst, wie viel Platz ein Ausschnitt des Textinhalts eines SVG-Textelements (<text>, <tspan>, <textPath>) in Schreibrichtung einnimmt. Das Ergebnis ist die Summe der Vorschub-Werte (Advance) der betroffenen Glyphen, inklusive letter-spacing und word-spacing, angegeben in Benutzereinheiten des Elements.

Typische Einsatzfälle sind das exakte Platzieren von Markierungen, Cursorn oder Hervorhebungen unter bestimmten Wörtern, das manuelle Kürzen von Beschriftungen in Diagrammen (z. B. mit Auslassungszeichen) oder das Berechnen von Tooltip-Positionen. Für die Länge des gesamten Textes gibt es die Kurzform getComputedTextLength().

Zu beachten: Der Wert beschreibt den Vorschub, nicht die visuelle Begrenzungsbox. Positionierungsattribute wie x, y, dx, dy oder rotate einzelner Zeichen werden laut SVG-2-Spezifikation nicht berücksichtigt; für tatsächliche Glyphenpositionen eignen sich getStartPositionOfChar() und getExtentOfChar().

Parameter

Name	Typ	Default	Beschreibung
$charnum Pflicht	number		Index des ersten Zeichens (0-basiert, gezählt in UTF-16-Codeeinheiten). Muss kleiner als `getNumberOfChars()` sein.
$nchars Pflicht	number		Anzahl der zu messenden Zeichen. Überschreitet `charnum + nchars` das Textende, wird bis zum letzten Zeichen gemessen.

Rückgabewert

Typ

number

Beschreibung

Die Vorschub-Länge des Teilstrings als Gleitkommazahl in Benutzereinheiten. Bei nchars = 0 ergibt sich 0.

Beispiele

Breite eines einzelnen Wortes messen

const svg = document.querySelector('svg');
const text = document.createElementNS('http://www.w3.org/2000/svg', 'text');
text.setAttribute('x', '10');
text.setAttribute('y', '40');
text.setAttribute('font-size', '20');
text.textContent = 'Hallo SVG-Welt';
svg.append(text); // Element muss gerendert sein

const start = text.textContent.indexOf('SVG');
const breite = text.getSubStringLength(start, 3);
console.log(`"SVG" ist ${breite.toFixed(1)} Einheiten breit`);

"SVG" ist 41.1 Einheiten breit (abhängig von der Schrift)

Wort im Text farbig unterlegen

const text = document.querySelector('#label');
const wort = 'wichtig';
const index = text.textContent.indexOf(wort);

if (index !== -1) {
  const offsetX = text.getSubStringLength(0, index);
  const breite = text.getSubStringLength(index, wort.length);
  const box = text.getBBox();

  const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
  rect.setAttribute('x', box.x + offsetX);
  rect.setAttribute('y', box.y);
  rect.setAttribute('width', breite);
  rect.setAttribute('height', box.height);
  rect.setAttribute('fill', 'gold');
  text.before(rect); // hinter den Text legen
}

Beschriftung mit Auslassungszeichen kürzen

const kuerzen = (textEl, maxBreite) => {
  const original = textEl.textContent;
  if (textEl.getComputedTextLength() <= maxBreite) return;

  let n = original.length;
  // so lange kürzen, bis Teilstring + '…' passt
  while (n > 0 && textEl.getSubStringLength(0, n) > maxBreite - 12) n--;
  textEl.textContent = original.slice(0, n) + '…';
};

kuerzen(document.querySelector('#achse-label'), 80);

// Wichtig · Fallstricke

Das Element muss im Dokument eingehängt und gerendert sein. Bei display: none oder nicht eingefügten Elementen liefern Browser 0 oder werfen Fehler.
Ist charnum negativ oder ≥ Anzahl der Zeichen, wird ein IndexSizeError (DOMException) geworfen.
Indizes zählen UTF-16-Codeeinheiten: Emojis und Zeichen außerhalb der BMP belegen zwei Positionen – String.prototype.length passt dazu, Iteration mit for…of dagegen nicht.
Browser unterscheiden sich im Detail (z. B. Kerning, Ligaturen, Berücksichtigung von dx); Ergebnisse sind schriftabhängig – Webfonts erst nach document.fonts.ready messen.
Wiederholte Aufrufe in Schleifen erzwingen Layout-Berechnungen; bei vielen Beschriftungen besser binär suchen oder Ergebnisse zwischenspeichern.

Siehe auch

SVGTextContentElement.getComputedTextLength() SVGTextContentElement.getExtentOfChar() SVGTextContentElement.getNumberOfChars() SVGTextContentElement.getRotationOfChar() SVGTextContentElement.getEndPositionOfChar()