SVGTransformList.initialize() — Methode · JavaScript-Referenz

Signatur

SVGTransformList.prototype.initialize(newItem)

Beschreibung

Die Methode initialize() der Schnittstelle SVGTransformList entfernt alle vorhandenen Transformationen aus der Liste und fügt danach das übergebene SVGTransform-Objekt als einziges Element ein. Das Ergebnis entspricht einem clear() mit anschließendem appendItem(), geschieht aber in einem einzigen Aufruf.

Sinnvoll ist das, wenn Sie das transform-Attribut eines SVG-Elements (z. B. <g>, <rect>, <path>) komplett ersetzen wollen, statt einzelne Einträge zu ändern. Typische Fälle sind Drag-&-Drop, Zoomen oder Drehen, bei denen in jedem Frame eine neu berechnete Gesamtmatrix gesetzt wird. Weil Sie mit Objekten statt mit Zeichenketten arbeiten, müssen Sie keine Attributtexte zusammenbauen und wieder auswerten.

Die Liste erreichen Sie über element.transform.baseVal (bei <linearGradient> über gradientTransform.baseVal, bei <pattern> über patternTransform.baseVal). Änderungen an baseVal werden sofort in das zugehörige Attribut übernommen. animVal ist dagegen schreibgeschützt.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGTransform		Die Transformation, die danach als einziges Element in der Liste steht. Ein neues Objekt erzeugen Sie mit `svgElement.createSVGTransform()` oder `svgElement.createSVGTransformFromMatrix(matrix)`.

Rückgabewert

Typ

SVGTransform

Beschreibung

Das Element, das in die Liste eingefügt wurde. Steckte newItem schon in einer anderen Liste, ist das nach SVG 2 eine Kopie und nicht das übergebene Objekt. Arbeiten Sie deshalb mit dem Rückgabewert weiter.

Beispiele

Transformation eines Elements vollständig ersetzen

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

// Anfangszustand: mehrere Transformationen
rect.setAttribute('transform', 'translate(10 10) scale(2)');

const rotation = svg.createSVGTransform();
rotation.setRotate(45, 50, 50);

const list = rect.transform.baseVal;
list.initialize(rotation);

console.log(list.numberOfItems);
console.log(rect.getAttribute('transform'));

1 rotate(45 50 50)

Aus einer Matrix initialisieren (z. B. beim Zoomen)

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

const zoomAt = (factor, cx, cy) => {
  // Skalierung um den Punkt (cx, cy)
  const matrix = svg.createSVGMatrix()
    .translate(cx, cy)
    .scale(factor)
    .translate(-cx, -cy);

  const t = svg.createSVGTransformFromMatrix(matrix);
  group.transform.baseVal.initialize(t);
};

zoomAt(1.5, 200, 150);
console.log(group.transform.baseVal.getItem(0).type === SVGTransform.SVG_TRANSFORM_MATRIX);

true

Drag & Drop: pro Mausbewegung nur eine Verschiebung

const svg = document.querySelector('svg');
const shape = svg.querySelector('circle');
const move = svg.createSVGTransform();
let active = false;

shape.addEventListener('pointerdown', () => { active = true; });
window.addEventListener('pointerup', () => { active = false; });

svg.addEventListener('pointermove', (event) => {
  if (!active) return;
  // Bildschirmkoordinaten in SVG-Koordinaten umrechnen
  const pt = new DOMPoint(event.clientX, event.clientY)
    .matrixTransform(svg.getScreenCTM().inverse());
  move.setTranslate(pt.x, pt.y);
  // Rückgabewert verwenden, da ggf. eine Kopie eingefügt wird
  const inserted = shape.transform.baseVal.initialize(move);
  console.log(inserted.matrix.e, inserted.matrix.f);
});

// Wichtig · Fallstricke

Kopie statt Original: Steckt newItem schon in einer anderen Liste, fügt SVG 2 eine Kopie ein. Nach SVG 1.1 wurde das Objekt dagegen aus der alten Liste entfernt. Wenn Sie später das ursprüngliche Objekt ändern, wirkt sich das deshalb nicht unbedingt auf das Element aus. Verwenden Sie den Rückgabewert.
Schreibgeschützte Listen: Ein Aufruf auf transform.animVal oder einer anderen schreibgeschützten Liste löst eine DOMException vom Typ NoModificationAllowedError aus.
Falscher Typ: Ist newItem kein SVGTransform, wird ein TypeError ausgelöst.
CSS-Transformationen: Die Methode ändert nur das SVG-Attribut transform. Eine CSS-Eigenschaft transform im Stylesheet oder im style-Attribut hat Vorrang und kann die Wirkung überdecken.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Wie das Attribut danach als Text aussieht (Leerzeichen oder Kommas, Zahlenformat), kann sich zwischen den Browsern leicht unterscheiden.

Siehe auch

SVGTransformList SVGTransformList.clear() SVGTransformList.appendItem() SVGTransformList.replaceItem() SVGTransformList.consolidate() SVGTransform SVGSVGElement.createSVGTransform() SVGSVGElement.createSVGTransformFromMatrix()