SVGLinearGradientElement.x1 — Eigenschaft · JavaScript-Referenz

Signatur

SVGLinearGradientElement.x1

Beschreibung

Die schreibgeschützte Eigenschaft x1 eines <linearGradient>-Elements gibt die x-Koordinate des Startpunkts des Verlaufsvektors zurück. Zusammen mit y1, x2 und y2 legt sie fest, in welche Richtung der Farbverlauf läuft. Ist das Attribut nicht gesetzt, gilt der Standardwert 0%.

Der Rückgabewert ist kein einfacher Wert, sondern ein SVGAnimatedLength. Über x1.baseVal erreichst du den im Markup bzw. per Skript gesetzten Grundwert (ein SVGLength, das du auch ändern kannst). x1.animVal liefert den aktuellen, eventuell durch SMIL-Animation (<animate>) veränderten Wert und lässt sich nur lesen.

Wie der Wert gedeutet wird, hängt von gradientUnits ab: Bei objectBoundingBox (Standard) bezieht sich der Wert auf den umgebenden Rahmen des gefüllten Elements (0 = linker Rand, 1 bzw. 100 % = rechter Rand). Bei userSpaceOnUse ist er eine absolute Koordinate im Benutzerkoordinatensystem. Praktisch ist die Eigenschaft für dynamische Verläufe, etwa um die Richtung eines Verlaufs abhängig von Mausposition oder Zeit zu drehen.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Objekt mit baseVal (änderbares SVGLength, Grundwert) und animVal (schreibgeschütztes SVGLength, aktueller animierter Wert) für das Attribut x1.

Beispiele

Startkoordinate eines Verlaufs auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const grad = document.createElementNS(svgNS, 'linearGradient');
grad.setAttribute('x1', '25%');

const len = grad.x1.baseVal;
console.log(len.valueAsString);   // Wert wie im Attribut
console.log(len.valueInSpecifiedUnits); // Zahl ohne Einheit
console.log(len.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

25% 25 true

Verlaufsrichtung per Skript ändern

// HTML: <svg><defs><linearGradient id="g">...</linearGradient></defs>
//        <rect width="200" height="100" fill="url(#g)"/></svg>
const grad = document.querySelector('#g');

// Neuen Wert mit Einheit setzen – aktualisiert auch das Attribut
grad.x1.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 50);
console.log(grad.getAttribute('x1'));

// Alternativ als String
grad.x1.baseVal.valueAsString = '10%';
console.log(grad.getAttribute('x1'));

50% 10%

Verlauf der Mausposition folgen lassen

const svg = document.querySelector('svg');
const grad = document.querySelector('#g');
// Mit objectBoundingBox wirken Werte zwischen 0 und 1
grad.setAttribute('gradientUnits', 'objectBoundingBox');

svg.addEventListener('pointermove', (event) => {
  const rect = svg.getBoundingClientRect();
  const ratio = (event.clientX - rect.left) / rect.width;
  grad.x1.baseVal.value = Math.min(Math.max(ratio, 0), 1);
  grad.x2.baseVal.value = 1 - grad.x1.baseVal.value;
});

// Wichtig · Fallstricke

x1 selbst ist schreibgeschützt: grad.x1 = 0.5 hat keine Wirkung (im Strict Mode ein TypeError). Ändere stattdessen grad.x1.baseVal oder setze das Attribut mit setAttribute('x1', …).
animVal ist schreibgeschützt; Schreibzugriffe lösen einen NoModificationAllowedError aus.
Das Setzen von baseVal.value nutzt Benutzereinheiten (ohne Einheit). Bei gradientUnits="objectBoundingBox" bedeutet 1 die volle Breite, nicht 1 Pixel – eine häufige Fehlerquelle.
Das Element muss mit document.createElementNS('http://www.w3.org/2000/svg', …) erzeugt werden; mit createElement entsteht ein HTML-Element ohne diese Eigenschaft.
Wird ein Verlauf per href von einem anderen Verlauf abgeleitet, spiegelt x1 nur das eigene Attribut wider, nicht den geerbten Wert.
Kompatibilität: in allen modernen Browsern verfügbar (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGLinearGradientElement SVGLinearGradientElement.y1 SVGLinearGradientElement.x2 SVGLinearGradientElement.y2 SVGAnimatedLength SVGLength SVGGradientElement