SVGTextPathElement.startOffset — Eigenschaft · JavaScript-Referenz

Signatur

SVGTextPathElement.startOffset

Beschreibung

Die Eigenschaft startOffset des Interfaces SVGTextPathElement gibt das Attribut startOffset des jeweiligen <textPath>-Elements als SVGAnimatedLength-Objekt zurück. Das Attribut legt fest, wie weit vom Anfang des Pfads entfernt der Text beginnt, also die Startposition entlang des Pfads.

Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein neues Objekt zuweisen. Über startOffset.baseVal (ein SVGLength) lässt sich der Wert aber lesen und ändern, zum Beispiel mit value, valueInSpecifiedUnits oder newValueSpecifiedUnits(). startOffset.animVal enthält den aktuellen Wert, wenn gerade eine SMIL-Animation läuft.

Typische Einsatzfälle sind laufende Schriftzüge entlang einer Kurve (Laufschrift-Effekte), das Zentrieren von Text auf einem Pfad (startOffset="50%" zusammen mit text-anchor="middle") und das Auslesen der Startposition, um die Darstellung zu berechnen.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (änderbarer Grundwert als SVGLength) und animVal (schreibgeschützter aktueller Wert während einer Animation). Fehlt das Attribut, ist der Wert 0.

Beispiele

Startversatz auslesen

// <svg><path id="kurve" d="M10,80 Q150,0 290,80"/>
// <text><textPath id="tp" href="#kurve" startOffset="25%">Hallo SVG</textPath></text></svg>
const tp = document.getElementById('tp');
const offset = tp.startOffset.baseVal;
console.log(offset.valueAsString);
console.log(offset.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

25% true

Text auf dem Pfad zentrieren

const tp = document.querySelector('textPath');
// Startversatz auf 50 % setzen und Text mittig verankern
tp.startOffset.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 50);
tp.setAttribute('text-anchor', 'middle');
console.log(tp.getAttribute('startOffset'));

50%

Laufschrift mit requestAnimationFrame

const tp = document.querySelector('textPath');
let prozent = 0;

const schritt = () => {
  prozent = (prozent + 0.2) % 100;
  tp.startOffset.baseVal.newValueSpecifiedUnits(
    SVGLength.SVG_LENGTHTYPE_PERCENTAGE,
    prozent
  );
  requestAnimationFrame(schritt);
};

requestAnimationFrame(schritt);

Zuweisung an die Eigenschaft selbst schlägt fehl

const tp = document.querySelector('textPath');
tp.startOffset = 100; // wird ignoriert (im strict mode: TypeError)
console.log(tp.startOffset instanceof SVGAnimatedLength);
// Richtig: über baseVal ändern
tp.startOffset.baseVal.value = 100;
console.log(tp.getAttribute('startOffset'));

true 100

// Wichtig · Fallstricke

Schreibgeschützt: Die Eigenschaft selbst lässt sich nicht überschreiben. Werte ändert man über startOffset.baseVal oder über setAttribute('startOffset', …).
Prozentwerte: Prozentangaben beziehen sich auf die Gesamtlänge des Pfads. Bei baseVal.value rechnet der Browser Prozentwerte in Benutzereinheiten um. Das Ergebnis hängt vom Pfad ab und ist nicht bei jeder Implementierung zuverlässig. Wer die Einheit behalten will, nutzt valueInSpecifiedUnits bzw. newValueSpecifiedUnits().
Negative Werte oder Werte über der Pfadlänge sind erlaubt. Zeichen außerhalb des Pfads werden dann nicht dargestellt.
Wird pathLength auf dem Pfad gesetzt, werden Längenangaben von startOffset auf diese Länge skaliert.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Für flüssige Animationen ist CSS oder SMIL (<animate attributeName=\"startOffset\">) oft effizienter als ständige DOM-Änderungen.

Siehe auch

SVGTextPathElement SVGTextPathElement.method SVGTextPathElement.spacing SVGAnimatedLength SVGLength SVGGeometryElement.getTotalLength() StorageEvent.storageArea