SVGTransform.setTranslate() — Methode · JavaScript-Referenz

Signatur

SVGTransform.prototype.setTranslate(tx, ty)

Beschreibung

Mit setTranslate() machen Sie ein bestehendes SVGTransform-Objekt zu einer reinen Verschiebung. Danach hat type den Wert SVGTransform.SVG_TRANSFORM_TRANSLATE (Wert 2) und die zugehörige Matrix lautet [1 0 0 1 tx ty]. Das entspricht dem Attribut transform="translate(tx, ty)".

Meist verwenden Sie die Methode zusammen mit SVGTransformList: Mit svg.createSVGTransform() erzeugen Sie eine neue Transformation, setzen sie mit setTranslate() und hängen sie per appendItem() an element.transform.baseVal an. Oder Sie ändern eine Transformation, die schon in der Liste steht. Das ist praktisch für Drag-and-drop, Animationen und interaktive Diagramme, denn Sie müssen dabei keine Attribut-Zeichenketten zusammenbauen und wieder zerlegen.

Das SVGTransform-Objekt ist live an das Element gebunden. Sobald Sie setTranslate() aufrufen, wird das Attribut transform aktualisiert und das Element neu dargestellt.

Parameter

Name	Typ	Default	Beschreibung
$tx Pflicht	number		Verschiebung entlang der x-Achse in Benutzereinheiten (user units).
$ty Pflicht	number		Verschiebung entlang der y-Achse in Benutzereinheiten. Anders als beim Attribut `translate(tx)` müssen Sie diesen Wert immer angeben, sonst kommt es zu einem `TypeError`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode ändert das Objekt direkt.

Beispiele

Neue Verschiebung an ein Element anhängen

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

// Neue Transformation erzeugen und als Verschiebung setzen
const t = svg.createSVGTransform();
t.setTranslate(50, 20);

rect.transform.baseVal.appendItem(t);

console.log(t.type === SVGTransform.SVG_TRANSFORM_TRANSLATE);
console.log(rect.getAttribute('transform'));

true translate(50 20)

Element per Maus verschieben (Drag-and-drop)

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

// Eine Verschiebung bereitstellen, die wir wiederverwenden
const move = svg.createSVGTransform();
move.setTranslate(0, 0);
circle.transform.baseVal.insertItemBefore(move, 0);

let start = null;

circle.addEventListener('pointerdown', (e) => {
  start = { x: e.clientX - move.matrix.e, y: e.clientY - move.matrix.f };
  circle.setPointerCapture(e.pointerId);
});

circle.addEventListener('pointermove', (e) => {
  if (!start) return;
  // Vereinfachung: 1 Bildschirmpixel = 1 Benutzereinheit
  move.setTranslate(e.clientX - start.x, e.clientY - start.y);
});

circle.addEventListener('pointerup', () => { start = null; });

Vorhandene Transformation umwandeln

const g = document.querySelector('#gruppe'); // <g transform="rotate(45)">
const first = g.transform.baseVal.getItem(0);

console.log(first.type); // 4 = SVG_TRANSFORM_ROTATE
first.setTranslate(10, 10);
console.log(first.type, first.angle);
console.log(g.getAttribute('transform'));

4 2 0 translate(10 10)

// Wichtig · Fallstricke

Ersetzt statt addiert: setTranslate() überschreibt die ganze Transformation, also auch eine vorhandene Rotation oder Skalierung. Um eine Verschiebung zusätzlich anzuwenden, hängen Sie eine eigene SVGTransform an die Liste an.
Nicht kumulativ: Wenn Sie setTranslate(5, 0) zweimal aufrufen, ergibt das weiterhin 5 und nicht 10. Für eine relative Verschiebung lesen Sie vorher matrix.e und matrix.f aus.
Nur Lesen bei animVal: Rufen Sie die Methode auf einer Transformation aus transform.animVal auf, wird NoModificationAllowedError ausgelöst.
Koordinaten: Die Werte sind Benutzereinheiten und keine Bildschirmpixel. Bei viewBox-Skalierung rechnen Sie Mauskoordinaten mit getScreenCTM().inverse() um.
CSS-Konflikt: Eine CSS-Eigenschaft transform auf dem Element hat Vorrang vor dem Attribut. Dann zeigt setTranslate() keine sichtbare Wirkung.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Für einfache Fälle ist element.style.transform oft kürzer.

Siehe auch

SVGTransform SVGTransform.setScale() SVGTransform.setRotate() SVGTransform.setMatrix() SVGTransformList SVGSVGElement.createSVGTransform() DataTransfer.setDragImage()