SVGTextPositioningElement.dy — Eigenschaft · JavaScript-Referenz

Signatur

readonly SVGTextPositioningElement.dy: SVGAnimatedLengthList

Beschreibung

Die schreibgeschützte Eigenschaft dy der Schnittstelle SVGTextPositioningElement bildet das SVG-Attribut dy von <text>- und <tspan>-Elementen ab. Anders als y legt dy keine absolute Position fest, sondern eine relative Verschiebung entlang der y-Achse gegenüber der aktuellen Textposition. Jeder Wert der Liste gilt für ein Zeichen: Der erste Wert verschiebt das erste Zeichen, der zweite das zweite usw. Hat die Liste weniger Einträge als Zeichen vorhanden sind, werden die restlichen Zeichen nicht zusätzlich verschoben.

Der Rückgabewert ist ein SVGAnimatedLengthList-Objekt mit zwei Listen vom Typ SVGLengthList:

baseVal – der Grundwert aus dem Attribut; änderbar, Änderungen werden sofort ins DOM zurückgeschrieben.
animVal – der aktuell animierte Wert (z. B. durch SMIL-<animate>); schreibgeschützt.

Typische Einsatzzwecke sind hoch- und tiefgestellte Textteile, Wellen- oder Treppeneffekte pro Buchstabe sowie Zeilenumbrüche in SVG-Text über mehrere <tspan>-Elemente mit dy="1.2em". Die Eigenschaft selbst kann nicht neu zugewiesen werden – verändert wird stattdessen der Inhalt von baseVal über Methoden wie appendItem(), clear() oder replaceItem(), oder alternativ direkt per setAttribute("dy", …).

Rückgabewert

Typ

SVGAnimatedLengthList

Beschreibung

Objekt mit baseVal (änderbare SVGLengthList) und animVal (schreibgeschützte, animierte SVGLengthList). Ist kein dy-Attribut gesetzt, sind beide Listen leer (numberOfItems === 0).

Beispiele

dy-Werte eines Textes auslesen

// <svg id="bild" width="300" height="100">
//   <text id="welle" x="10" y="50" dy="0 -5 5 -5 5">Hallo</text>
// </svg>
const text = document.getElementById("welle");
const liste = text.dy.baseVal;

console.log(liste.numberOfItems);
for (let i = 0; i < liste.numberOfItems; i++) {
  const laenge = liste.getItem(i);
  console.log(`Zeichen ${i}: ${laenge.valueAsString}`);
}

5 Zeichen 0: 0 Zeichen 1: -5 Zeichen 2: 5 Zeichen 3: -5 Zeichen 4: 5

Wellen-Effekt pro Buchstabe per Skript erzeugen

const svg = document.getElementById("bild");
const text = document.getElementById("welle");
const liste = text.dy.baseVal;
liste.clear();

const zeichen = text.textContent.length;
for (let i = 0; i < zeichen; i++) {
  const laenge = svg.createSVGLength();
  // Sinuswelle: abwechselnd nach oben und unten verschieben
  laenge.value = i === 0 ? 0 : Math.round(Math.sin(i) * 6);
  liste.appendItem(laenge);
}

console.log(text.getAttribute("dy"));

0 5 5 1 -5

Hochgestellten Text mit tspan und em-Einheit

// <text id="formel" x="10" y="40">E = mc<tspan id="hoch">2</tspan></text>
const svg = document.querySelector("svg");
const hoch = document.getElementById("hoch");

const verschiebung = svg.createSVGLength();
verschiebung.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_EMS, -0.5);
hoch.dy.baseVal.initialize(verschiebung);
hoch.setAttribute("font-size", "0.7em");

console.log(hoch.dy.baseVal.getItem(0).valueAsString);

-0.5em

// Wichtig · Fallstricke

Relativ, nicht absolut: dy verschiebt gegenüber der aktuellen Textposition und wirkt kumulativ – eine Verschiebung bleibt für alle folgenden Zeichen bestehen. Für absolute Positionen y verwenden.
Die Eigenschaft selbst ist schreibgeschützt: text.dy = … hat keine Wirkung (bzw. wirft im strikten Modus einen TypeError). Änderungen erfolgen über dy.baseVal oder setAttribute().
animVal kann nicht verändert werden; Schreibversuche lösen eine NoModificationAllowedError-DOMException aus.
SVGLength-Objekte werden über SVGSVGElement.createSVGLength() erzeugt, nicht per new SVGLength().
Ein SVGLength-Objekt, das bereits in einer anderen Liste steckt, wird von appendItem()/initialize() kopiert bzw. dort entfernt – je nach Browser leicht unterschiedlich. Sicherer ist es, für jede Liste neue Objekte anzulegen.
Relative Einheiten wie em oder % liefern bei value den in Benutzereinheiten umgerechneten Wert; der Rohwert steht in valueInSpecifiedUnits.
Kompatibilität: In allen modernen Browsern seit Langem verfügbar (SVG 1.1). SMIL-Animationen, die animVal befüllen, werden ebenfalls breit unterstützt.

Siehe auch

SVGTextPositioningElement.dx SVGTextPositioningElement.y SVGTextPositioningElement.x SVGTextPositioningElement.rotate SVGAnimatedLengthList SVGLengthList SVGSVGElement.createSVGLength() SVGTSpanElement