SVGFEDisplacementMapElement.x — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEDisplacementMapElement.x

Beschreibung

Die Eigenschaft x der Schnittstelle SVGFEDisplacementMapElement gibt die horizontale Koordinate der linken oberen Ecke der Filterprimitiv-Unterregion eines <feDisplacementMap>-Elements zurück. Diese Region begrenzt, in welchem Bereich das Ergebnis des Verschiebungseffekts berechnet und dargestellt wird.

Der Wert ist ein SVGAnimatedLength-Objekt mit zwei Teilen: baseVal enthält den im Attribut gesetzten Grundwert (eine SVGLength, die sich verändern lässt), animVal ist der aktuell wirksame, unter Umständen durch SMIL-Animation veränderte Wert, der nur gelesen werden kann. Die Eigenschaft selbst ist schreibgeschützt, du kannst ihr also kein neues Objekt zuweisen, wohl aber baseVal.value bzw. baseVal.valueAsString ändern.

Wie der Wert zu interpretieren ist, hängt vom Attribut primitiveUnits des umgebenden <filter> ab: Bei userSpaceOnUse (Standard) sind es Benutzerkoordinaten, bei objectBoundingBox Bruchteile bzw. Prozentwerte der Begrenzungsbox des gefilterten Elements. Fehlt das Attribut, ist der Standardwert 0% der Filterregion.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (veränderbare SVGLength des Attributwerts) und animVal (schreibgeschützte, aktuell animierte SVGLength).

Beispiele

x-Koordinate eines feDisplacementMap auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
svg.innerHTML = `
  <filter id="wobble">
    <feTurbulence type="turbulence" baseFrequency="0.05" result="noise" />
    <feDisplacementMap in="SourceGraphic" in2="noise" scale="20" x="10" y="5" width="200" height="100" />
  </filter>`;
document.body.append(svg);

const disp = svg.querySelector('feDisplacementMap');
console.log(disp.x.baseVal.value);
console.log(disp.x.animVal.value);
console.log(disp.x instanceof SVGAnimatedLength);

10 10 true

Unterregion per Skript verschieben

const disp = document.querySelector('#wobble feDisplacementMap');

// Zahlenwert in Benutzereinheiten setzen
disp.x.baseVal.value = 40;
console.log(disp.getAttribute('x'));

// Oder mit Einheit als Zeichenkette
disp.x.baseVal.valueAsString = '25%';
console.log(disp.getAttribute('x'));

40 25%

Einheit prüfen und in Pixel umrechnen

const disp = document.querySelector('feDisplacementMap');
const len = disp.x.baseVal;

if (len.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE) {
  console.log(`Prozentwert: ${len.valueInSpecifiedUnits}%`);
} else {
  // In Benutzereinheiten konvertieren
  len.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_NUMBER);
  console.log(`Benutzereinheiten: ${len.value}`);
}

Benutzereinheiten: 10

// Wichtig · Fallstricke

Schreibgeschützt: disp.x = 50 hat keine Wirkung (bzw. wirft im Strict-Mode einen TypeError). Ändere stattdessen disp.x.baseVal.value oder nutze setAttribute('x', …).
animVal ist immer nur lesbar; Schreibversuche lösen eine NoModificationAllowedError-Ausnahme aus.
Prozentwerte beziehen sich auf die Filterregion, nicht auf das SVG-Viewport – bei primitiveUnits="objectBoundingBox" werden Werte wie 0.1 als Anteil der Begrenzungsbox interpretiert. Das führt häufig zu unerwartet abgeschnittenen Effekten.
Das Element muss im SVG-Namensraum erzeugt werden (createElementNS); mit document.createElement('feDisplacementMap') entsteht ein unbekanntes HTML-Element ohne diese Eigenschaft.
Kompatibilität: in allen modernen Browsern (Chrome, Firefox, Safari, Edge) seit Langem unterstützt.

Siehe auch

SVGFEDisplacementMapElement SVGFEDisplacementMapElement.y SVGFEDisplacementMapElement.width SVGFEDisplacementMapElement.height SVGAnimatedLength SVGLength