SVGTextPathElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGTextPathElement extends SVGTextContentElement

Beschreibung

SVGTextPathElement ist die DOM-Schnittstelle für das Element <textPath>. Das Element steht innerhalb eines <text>-Elements und setzt seinen Text entlang der Form eines <path> (oder einer anderen Grundform). Die Referenz auf den Pfad läuft über das Attribut href. Typische Anwendungen sind Beschriftungen auf Kreisbögen, Logos, Stempel, Straßennamen auf Karten oder animierte Laufschriften.

Die Schnittstelle erbt von SVGTextContentElement. Damit stehen alle Text-Messmethoden wie getComputedTextLength(), getNumberOfChars() oder getStartPositionOfChar() zur Verfügung. Außerdem implementiert sie SVGURIReference. Selbst definiert sie diese Eigenschaften:

href (SVGAnimatedString): Verweis auf den Pfad, z. B. "#kreis".
startOffset (SVGAnimatedLength): Startposition des Texts auf dem Pfad, als Länge oder in Prozent.
method (SVGAnimatedEnumeration): Darstellungsart der Glyphen, also align oder stretch.
spacing (SVGAnimatedEnumeration): Berechnung der Abstände, also auto oder exact.

Dazu kommen die Konstanten TEXTPATH_METHODTYPE_UNKNOWN (0), TEXTPATH_METHODTYPE_ALIGN (1), TEXTPATH_METHODTYPE_STRETCH (2) sowie TEXTPATH_SPACINGTYPE_UNKNOWN (0), TEXTPATH_SPACINGTYPE_AUTO (1) und TEXTPATH_SPACINGTYPE_EXACT (2). Alle „animierten“ Eigenschaften liefern ein Objekt mit baseVal (der gesetzte Wert, schreibbar) und animVal (der aktuelle Wert während einer SMIL-Animation, nur lesbar).

Rückgabewert

Typ

SVGTextPathElement

Beschreibung

Instanzen bekommt man über document.createElementNS("http://www.w3.org/2000/svg", "textPath") oder über DOM-Abfragen wie querySelector("textPath"). Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

textPath dynamisch erzeugen: Text auf einem Kreisbogen

const SVG_NS = 'http://www.w3.org/2000/svg';

const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('viewBox', '0 0 200 200');
svg.setAttribute('width', '200');

// Pfad definieren, der als Führungslinie dient
const path = document.createElementNS(SVG_NS, 'path');
path.id = 'bogen';
path.setAttribute('d', 'M 20,100 A 80,80 0 0 1 180,100');
path.setAttribute('fill', 'none');
path.setAttribute('stroke', '#ccc');

const text = document.createElementNS(SVG_NS, 'text');
const textPath = document.createElementNS(SVG_NS, 'textPath');

// href über die animierte Eigenschaft setzen
textPath.href.baseVal = '#bogen';
textPath.textContent = 'programmierung.net';

text.append(textPath);
svg.append(path, text);
document.body.append(svg);

console.log(textPath instanceof SVGTextPathElement);
console.log(textPath.href.baseVal);

true #bogen

Text mittig auf dem Pfad ausrichten (startOffset in Prozent)

const textPath = document.querySelector('textPath');

// 50 % der Pfadlänge als Startpunkt
textPath.startOffset.baseVal.newValueSpecifiedUnits(
  SVGLength.SVG_LENGTHTYPE_PERCENTAGE,
  50
);
// Text um diesen Punkt zentrieren
textPath.setAttribute('text-anchor', 'middle');

console.log(textPath.getAttribute('startOffset'));
console.log(textPath.startOffset.baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

50% true

Laufschrift: startOffset per requestAnimationFrame animieren

const textPath = document.querySelector('#laufschrift textPath');
const offset = textPath.startOffset.baseVal;
let prozent = 0;

const tick = () => {
  prozent = (prozent + 0.3) % 100;
  offset.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, prozent);
  requestAnimationFrame(tick);
};

requestAnimationFrame(tick);

method, spacing und Textlänge auslesen

const tp = document.querySelector('textPath');

const methoden = {
  [SVGTextPathElement.TEXTPATH_METHODTYPE_UNKNOWN]: 'unknown',
  [SVGTextPathElement.TEXTPATH_METHODTYPE_ALIGN]: 'align',
  [SVGTextPathElement.TEXTPATH_METHODTYPE_STRETCH]: 'stretch'
};

console.log('method:', methoden[tp.method.baseVal]);
console.log('spacing exact?', tp.spacing.baseVal === SVGTextPathElement.TEXTPATH_SPACINGTYPE_EXACT);

// geerbt von SVGTextContentElement
console.log('Textlänge:', tp.getComputedTextLength().toFixed(1));

method: align spacing exact? false Textlänge: 142.7

// Wichtig · Fallstricke

Namensraum: SVG-Elemente müssen Sie mit createElementNS('http://www.w3.org/2000/svg', 'textPath') erzeugen. document.createElement('textPath') liefert nur ein nutzloses HTMLUnknownElement.
href gegenüber xlink:href: Seit SVG 2 reicht das einfache Attribut href. Sehr alte Browser, ältere Safari-Versionen und manche Werkzeuge wie Inkscape oder ältere Renderer brauchen noch xlink:href (über setAttributeNS('http://www.w3.org/1999/xlink', 'href', ...)). Wer beide Attribute setzt, ist auf der sicheren Seite.
Unterstützung von method/spacing: Die Eigenschaften lassen sich zwar lesen und schreiben, aber viele Browser werten method="stretch" und spacing="exact" beim Zeichnen nicht aus.
SVG-2-Attribute: side (Text auf der anderen Seite des Pfads) wird bislang praktisch nur von Firefox unterstützt. Das Attribut path (Pfaddaten direkt am Element) wird kaum unterstützt. Für beide gibt es keine eigenen DOM-Eigenschaften. Verwenden Sie in der Praxis einen referenzierten <path>.
Überstehender Text: Ist der Text länger als der Pfad, werden die Zeichen hinter dem Pfadende nicht angezeigt. Mit getComputedTextLength() und SVGPathElement.getTotalLength() können Sie das vorher prüfen.
Performance: Wenn Sie startOffset in jedem Frame ändern, muss das Text-Layout jedes Mal neu berechnet werden. Bei vielen Elementen oder langen Texten kann das spürbar Rechenzeit kosten.

Siehe auch

SVGClipPathElement SVGMPathElement SVGPathElement SVGTextElement SVGMetadataElement