SVGTextPositioningElement.dx — Eigenschaft · JavaScript-Referenz

Signatur

readonly SVGTextPositioningElement.dx: SVGAnimatedLengthList

Beschreibung

Die schreibgeschützte Eigenschaft dx der Schnittstelle SVGTextPositioningElement gibt das Attribut dx eines SVGTextElement (<text>) oder SVGTSpanElement (<tspan>) als SVGAnimatedLengthList zurück. Anders als x gibt dx keine absoluten Koordinaten an, sondern relative Verschiebungen entlang der x-Achse: Der erste Wert verschiebt das erste Zeichen, der zweite das zweite Zeichen usw. Die Verschiebungen addieren sich zur aktuellen Textposition.

Das zurückgegebene Objekt hat zwei Eigenschaften: baseVal (die im Attribut festgelegten Werte, veränderbar) und animVal (die aktuellen Werte inklusive SMIL-Animationen, schreibgeschützt). Beide sind SVGLengthList-Objekte mit Methoden wie getItem(), appendItem(), replaceItem(), removeItem() und clear().

Typische Einsatzfälle sind Unterschneidung (Kerning) einzelner Buchstaben, das Ausrichten von Text-Teilen relativ zueinander oder Effekte, bei denen Zeichen gezielt auseinandergezogen werden – ohne für jedes Zeichen absolute Koordinaten berechnen zu müssen. Änderungen an baseVal werden sofort in das DOM-Attribut übertragen und umgekehrt.

Rückgabewert

Typ

SVGAnimatedLengthList

Beschreibung

Ein Live-Objekt mit baseVal und animVal (jeweils SVGLengthList), das die Werte des dx-Attributs widerspiegelt. Ist das Attribut nicht gesetzt, sind beide Listen leer.

Beispiele

dx-Werte eines tspan auslesen

// HTML: <svg><text x="10" y="30"><tspan id="wort" dx="5 10 15">ABC</tspan></text></svg>
const tspan = document.querySelector('#wort');
const liste = tspan.dx.baseVal;

console.log(liste.numberOfItems);
for (let i = 0; i < liste.numberOfItems; i++) {
  console.log(liste.getItem(i).value);
}

3 5 10 15

Verschiebung per Skript anhängen und ändern

const svg = document.querySelector('svg');
const text = svg.querySelector('text');

// Neue Länge erzeugen (Einheit: Benutzereinheiten)
const laenge = svg.createSVGLength();
laenge.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_NUMBER, 8);

text.dx.baseVal.clear();
text.dx.baseVal.appendItem(laenge);

// Vorhandenen Eintrag direkt ändern (Live-Referenz)
text.dx.baseVal.getItem(0).value = 12;

console.log(text.getAttribute('dx'));

12

Buchstaben auseinanderziehen (Sperrsatz-Effekt)

const NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(NS, 'svg');
svg.setAttribute('width', '300');
svg.setAttribute('height', '60');
const text = document.createElementNS(NS, 'text');
text.setAttribute('x', '10');
text.setAttribute('y', '40');
text.textContent = 'SPERRE';
svg.append(text);
document.body.append(svg);

// Jedem Zeichen außer dem ersten 4 Einheiten Abstand geben
const sperren = (el, abstand) => {
  const liste = el.dx.baseVal;
  liste.clear();
  [...el.textContent].forEach((_, i) => {
    const l = svg.createSVGLength();
    l.value = i === 0 ? 0 : abstand;
    liste.appendItem(l);
  });
};

sperren(text, 4);
console.log(text.getAttribute('dx'));

0 4 4 4 4 4

// Wichtig · Fallstricke

Schreibgeschützt: element.dx = … hat keine Wirkung (im Strict Mode TypeError). Werte ändert man über dx.baseVal oder mit setAttribute('dx', '…').
animVal ist immer schreibgeschützt; Schreibversuche lösen eine DOMException (NoModificationAllowedError) aus.
dx ist relativ und wirkt kumulativ: Eine Verschiebung beim zweiten Zeichen verschiebt auch alle folgenden. Gibt es weniger Werte als Zeichen, erhalten die restlichen Zeichen keine zusätzliche Verschiebung (ein dx am Elternelement kann aber greifen).
SVGLength.value liefert stets Benutzereinheiten. Bei %- oder em-Werten hängt das Ergebnis vom Viewport bzw. der Schriftgröße ab; für die ursprüngliche Einheit valueInSpecifiedUnits und unitType verwenden.
appendItem() fügt ein bereits in einer anderen Liste enthaltenes SVGLength nicht als Kopie ein, sondern verschiebt es in einigen älteren Implementierungen – im Zweifel immer neue Objekte mit createSVGLength() erzeugen.
Unterstützt von allen modernen Browsern; die Eigenschaft length von SVGLengthList ist neuer als numberOfItems – für maximale Kompatibilität numberOfItems nutzen.

Siehe auch

SVGTextPositioningElement.dy SVGTextPositioningElement.x SVGTextPositioningElement.y SVGTextPositioningElement.rotate SVGFECompositeElement.x