SVGTextContentElement.textLength — Eigenschaft · JavaScript-Referenz

Signatur

SVGTextContentElement.textLength

Beschreibung

Die Eigenschaft textLength steht auf allen SVG-Textinhaltselementen zur Verfügung, also auf <text>, <tspan> und <textPath>. Sie gibt ein SVGAnimatedLength-Objekt zurück, das das Attribut textLength widerspiegelt. Mit diesem Attribut legt der Autor fest, wie breit der Text dargestellt werden soll. Der Browser streckt oder staucht den Text dann passend dazu.

Schreibgeschützt ist nur die Eigenschaft selbst: Man kann ihr kein neues Objekt zuweisen. Den Wert kann man trotzdem ändern, und zwar über textLength.baseVal, ein SVGLength-Objekt mit value, valueInSpecifiedUnits, unitType und newValueSpecifiedUnits(). textLength.animVal enthält den aktuell wirksamen Wert, falls SMIL-Animationen laufen.

Wie der Text an die Länge angepasst wird, bestimmt das Attribut lengthAdjust (DOM-Eigenschaft lengthAdjust): spacing ändert nur die Abstände zwischen den Zeichen, spacingAndGlyphs verzerrt zusätzlich die Glyphen. Typische Einsatzfälle sind Beschriftungen mit fester Breite, etwa in Diagrammen, Badges oder Logos, deren Breite unabhängig von der Schriftart gleich bleiben soll.

Ist das Attribut nicht gesetzt, liefert baseVal.value in der Regel 0. Die tatsächlich gerenderte Länge liefert dann getComputedTextLength().

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (der gesetzte Wert, änderbar, vom Typ SVGLength) und animVal (der aktuell animierte Wert, nur lesbar).

Beispiele

Gesetzten textLength-Wert auslesen

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.innerHTML = '<text id="label" x="10" y="30" textLength="200">Hallo SVG</text>';
document.body.append(svg);

const text = svg.querySelector('#label');
const { baseVal } = text.textLength;
console.log(baseVal.value);      // Wert in Benutzereinheiten
console.log(baseVal.unitType === SVGLength.SVG_LENGTHTYPE_NUMBER);

200 true

Textbreite dynamisch festlegen (Badge mit fester Breite)

const setBadgeWidth = (textEl, width) => {
  // baseVal ist beschreibbar, textLength selbst nicht
  textEl.textLength.baseVal.value = width;
  textEl.lengthAdjust.baseVal = SVGTextContentElement.LENGTHADJUST_SPACINGANDGLYPHS;
};

const badge = document.querySelector('svg text.badge');
setBadgeWidth(badge, 120);
console.log(badge.getAttribute('textLength'));

120

Gesetzte und tatsächliche Länge vergleichen

const text = document.querySelector('text');
const declared = text.textLength.baseVal.value;
const rendered = text.getComputedTextLength();

if (declared === 0) {
  console.log(`Kein textLength gesetzt, natürliche Breite: ${rendered.toFixed(1)}`);
} else {
  console.log(`Vorgabe: ${declared}, gerendert: ${rendered.toFixed(1)}`);
}

Kein textLength gesetzt, natürliche Breite: 64.3

Einheit umstellen mit newValueSpecifiedUnits()

const text = document.querySelector('text');
// Breite auf 50 % des Viewports setzen
text.textLength.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 50);
console.log(text.getAttribute('textLength'));

50%

// Wichtig · Fallstricke

Nicht direkt zuweisen: text.textLength = 100 hat keine Wirkung, im Strict Mode wird ein TypeError ausgelöst. Den Wert ändert man immer über textLength.baseVal.value oder per setAttribute('textLength', '100').
Nicht mit getComputedTextLength() verwechseln: textLength spiegelt nur das gesetzte Attribut wider. Ist es nicht gesetzt, ist der Wert 0; die tatsächlich gerenderte Breite liefert nur getComputedTextLength().
Bei verschachtelten <tspan>-Elementen gilt textLength nur für das jeweilige Element. Wenn Werte auf Eltern- und Kindelement gesetzt sind, kann das zu unerwarteten Ergebnissen führen.
Bei lengthAdjust="spacingAndGlyphs" werden die Glyphen verzerrt. Bei starker Stauchung leidet die Lesbarkeit.
Relative Einheiten (%, em) erfordern ein gerendertes Element im Dokument. Sonst liefert baseVal.value unter Umständen 0 oder löst einen Fehler aus.
Die Eigenschaft wird in allen modernen Browsern unterstützt. Wie gestreckt wird, besonders bei <textPath>, kann sich zwischen den Browser-Engines leicht unterscheiden.

Siehe auch

HTMLTextAreaElement.minLength SVGTextContentElement.lengthAdjust HTMLTextAreaElement.textLength HTMLTextAreaElement.maxLength SVGGeometryElement.pathLength