SVGTextContentElement.getRotationOfChar() — Methode · JavaScript-Referenz

Signatur

SVGTextContentElement.prototype.getRotationOfChar(index)

Beschreibung

Die Methode getRotationOfChar() ist auf allen Textinhalts-Elementen von SVG verfügbar, also auf <text>, <tspan> und <textPath>. Sie liefert die Summe aller Drehungen, die auf ein einzelnes typografisches Zeichen angewendet werden. Der Wert ist in Grad angegeben und bezieht sich auf das aktuelle Benutzerkoordinatensystem des Elements.

In diese Drehung fließen vor allem zwei Quellen ein:

das Attribut rotate auf <text> bzw. <tspan>, das einzelnen Zeichen eigene Winkel zuweist,
die Ausrichtung entlang eines Pfades bei <textPath>. Dabei folgt jedes Zeichen der Tangente der Kurve.

Das Attribut transform des Elements oder seiner Vorfahren ist dagegen nicht enthalten, weil es das Koordinatensystem selbst verändert.

Typische Einsatzfälle sind Beschriftungen, die entlang von Pfaden laufen, Werkzeuge zur Textbearbeitung in SVG-Editoren und das Platzieren von Hervorhebungen, Cursorn oder Hilfsgrafiken, die genauso gedreht sein sollen wie ein bestimmtes Zeichen. Oft kombiniert man die Methode mit getStartPositionOfChar() und getExtentOfChar(), um Position, Ausmaße und Winkel eines Zeichens vollständig zu bestimmen.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index des Zeichens innerhalb des Elements. Er muss zwischen `0` und `getNumberOfChars() - 1` liegen. Gezählt werden UTF-16-Codeeinheiten.

Rückgabewert

Typ

number

Beschreibung

Die Drehung des Zeichens in Grad (Gleitkommazahl). Ohne Drehung ist der Wert 0. Liegt index außerhalb des gültigen Bereichs, wird eine DOMException vom Typ IndexSizeError ausgelöst.

Beispiele

Drehwinkel aus dem rotate-Attribut auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
svg.setAttribute('width', '300');
svg.setAttribute('height', '100');

const text = document.createElementNS(svgNS, 'text');
text.setAttribute('x', '20');
text.setAttribute('y', '60');
text.setAttribute('rotate', '0 15 30 45');
text.textContent = 'SVG!';

svg.append(text);
document.body.append(svg); // Das Element muss gerendert sein

for (let i = 0; i < text.getNumberOfChars(); i++) {
  console.log(`${text.textContent[i]}: ${text.getRotationOfChar(i)}°`);
}

S: 0° V: 15° G: 30° !: 45°

Winkel der Zeichen entlang eines textPath

// HTML:
// <svg width="400" height="200">
//   <path id="kurve" d="M 20 150 Q 200 0 380 150" fill="none" stroke="#ccc"/>
//   <text><textPath id="beschriftung" href="#kurve">Bogenbeschriftung</textPath></text>
// </svg>

const textPath = document.getElementById('beschriftung');
const anzahl = textPath.getNumberOfChars();

const winkel = Array.from({ length: anzahl }, (_, i) =>
  Math.round(textPath.getRotationOfChar(i))
);

console.log('Erstes Zeichen:', winkel[0]);
console.log('Letztes Zeichen:', winkel.at(-1));

Erstes Zeichen: -39 Letztes Zeichen: 38 (Die genauen Werte hängen von Schrift und Pfad ab.)

Markierung passend zum Zeichen drehen

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

const markiereZeichen = (textEl, index) => {
  const start = textEl.getStartPositionOfChar(index);
  const winkel = textEl.getRotationOfChar(index);
  const breite = textEl.getSubStringLength(index, 1);

  const rect = document.createElementNS(svgNS, 'rect');
  rect.setAttribute('x', start.x);
  rect.setAttribute('y', start.y - 16);
  rect.setAttribute('width', breite);
  rect.setAttribute('height', 20);
  rect.setAttribute('fill', 'rgba(255, 200, 0, 0.4)');
  // Um den Startpunkt des Zeichens drehen
  rect.setAttribute('transform', `rotate(${winkel} ${start.x} ${start.y})`);

  textEl.ownerSVGElement.insertBefore(rect, textEl);
};

const text = document.querySelector('svg text');
try {
  markiereZeichen(text, 3);
} catch (err) {
  if (err.name === 'IndexSizeError') {
    console.warn('Index außerhalb des Textes');
  }
}

// Wichtig · Fallstricke

Ungültiger Index: Negative Werte oder Werte ab getNumberOfChars() lösen einen IndexSizeError aus. Prüfen Sie den Index vorher oder fangen Sie den Fehler mit try/catch ab.
Gerendertes Element erforderlich: Die Methode braucht ein berechnetes Layout. Bei Elementen, die nicht im Dokument hängen oder mit display: none ausgeblendet sind, liefern Browser unzuverlässige Ergebnisse oder lösen Fehler aus.
transform wird nicht berücksichtigt: Drehungen durch das Attribut transform oder durch CSS-Transformationen gehören nicht zum Rückgabewert. Den Gesamtwinkel auf dem Bildschirm erhalten Sie zusätzlich über getCTM() bzw. getScreenCTM().
Zeichen und Glyphen: Der Index zählt UTF-16-Codeeinheiten, nicht sichtbare Glyphen. Bei Emojis, Ersatzpaaren (Surrogatpaaren) oder Ligaturen können mehrere Indizes zu einer Glyphe gehören.
rotate-Attribut: Gibt das Attribut weniger Werte an, als der Text Zeichen hat, übernehmen die übrigen Zeichen den letzten Wert.
Kompatibilität: Wird von allen modernen Browsern (Chrome, Firefox, Safari, Edge) unterstützt. Bei textPath können sich die Werte je nach Rendering-Engine leicht unterscheiden.

Siehe auch

SVGTextContentElement.getEndPositionOfChar() SVGTextContentElement.getExtentOfChar() SVGTextContentElement.getStartPositionOfChar() SVGTextContentElement.getNumberOfChars() SVGTextContentElement.getSubStringLength()