SVGTransformList.getItem() — Methode · JavaScript-Referenz

Signatur

SVGTransformList.prototype.getItem(index)

Beschreibung

Mit getItem() greifen Sie über den Index auf eine einzelne Transformation in einer SVGTransformList zu. So eine Liste bekommen Sie typischerweise über element.transform.baseVal, zum Beispiel bei <g>, <rect> oder <path>. Jeder Eintrag entspricht einer Funktion im transform-Attribut, also etwa translate(…), rotate(…) oder scale(…).

Zurück kommt eine Live-Referenz auf das SVGTransform-Objekt in der Liste. Wenn Sie es ändern, etwa mit setTranslate(), setRotate() oder setScale(), schreibt der Browser das sofort ins transform-Attribut zurück, und die Grafik wird neu gezeichnet. Deshalb eignet sich getItem() gut, um in Animationen oder bei Drag-and-Drop einzelne Transformationen gezielt anzupassen, ohne den Attribut-String jedes Mal neu zu parsen.

Die Anzahl der Einträge steht in numberOfItems (in neueren Browsern auch in length). In modernen Browsern können Sie auch mit eckigen Klammern zugreifen (list[0]). Nur getItem() wirft aber bei einem ungültigen Index eine eindeutige Ausnahme.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index des gewünschten Eintrags. Muss zwischen `0` und `numberOfItems - 1` liegen.

Rückgabewert

Typ

SVGTransform

Beschreibung

Das SVGTransform-Objekt an der angegebenen Position, als Live-Referenz auf den Listeneintrag.

Beispiele

Transformationen eines Elements auslesen

// <svg><rect id="box" width="50" height="50" transform="translate(20,30) rotate(45)"/></svg>
const rect = document.getElementById('box');
const list = rect.transform.baseVal;

const typeNames = {
  [SVGTransform.SVG_TRANSFORM_TRANSLATE]: 'translate',
  [SVGTransform.SVG_TRANSFORM_ROTATE]: 'rotate',
  [SVGTransform.SVG_TRANSFORM_SCALE]: 'scale'
};

for (let i = 0; i < list.numberOfItems; i++) {
  const t = list.getItem(i);
  console.log(i, typeNames[t.type] ?? t.type, t.matrix.e, t.matrix.f);
}

0 translate 20 30 1 rotate 0 0

Verschiebung beim Ziehen live anpassen

const svg = document.querySelector('svg');
const group = document.querySelector('#draggable');

// Sicherstellen, dass an Index 0 eine translate-Transformation steht
const list = group.transform.baseVal;
if (list.numberOfItems === 0) {
  const t = svg.createSVGTransform();
  t.setTranslate(0, 0);
  list.appendItem(t);
}

const translate = list.getItem(0); // Live-Referenz

group.addEventListener('pointermove', (event) => {
  if (event.buttons !== 1) return;
  // Änderung wirkt sofort auf das transform-Attribut
  translate.setTranslate(
    translate.matrix.e + event.movementX,
    translate.matrix.f + event.movementY
  );
});

Ungültigen Index abfangen

const list = document.querySelector('rect').transform.baseVal;

try {
  list.getItem(99);
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Liegt der Index außerhalb des gültigen Bereichs, wirft die Methode eine DOMException vom Typ IndexSizeError. Sie gibt dann nicht undefined zurück.
Das zurückgegebene Objekt ist keine Kopie. Jede Änderung daran ändert sofort das transform-Attribut. Wenn Sie den Wert unverändert behalten möchten, lesen Sie die Werte aus t.matrix in eigene Variablen aus.
Nutzen Sie baseVal für Änderungen. animVal ist schreibgeschützt und spiegelt den Zustand während einer SMIL-Animation wider.
CSS-Transformationen (style.transform oder Stylesheets) tauchen nicht in der SVGTransformList auf. Die Liste enthält nur, was im transform-Attribut steht.
Die Methode wird von allen modernen Browsern unterstützt. Die Eigenschaft length und der Zugriff per Index (list[i]) sind neuer als numberOfItems und getItem(). Wenn ältere Umgebungen mitlaufen sollen, ist getItem() die sicherere Wahl.

Siehe auch

SVGTransformList SVGTransform SVGTransformList.numberOfItems SVGTransformList.appendItem() SVGTransformList.replaceItem() SVGTransformList.consolidate() SVGSVGElement.createSVGTransform()