SVGLinearGradientElement.x2 — Eigenschaft · JavaScript-Referenz

Signatur

SVGLinearGradientElement.x2

Beschreibung

Die Eigenschaft x2 des Interfaces SVGLinearGradientElement gibt das Attribut x2 eines <linearGradient>-Elements zurück. Zusammen mit y2 legt es den Endpunkt des Gradientenvektors fest. Hinweis: Die MDN-Kurzbeschreibung spricht vom „Startpunkt“. Das stimmt nicht, denn der Startpunkt wird durch x1/y1 bestimmt. An diesem Punkt wird der Farbstopp mit offset="100%" dargestellt.

Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein neues Objekt zuweisen. Das zurückgegebene SVGAnimatedLength-Objekt ist aber veränderbar. Über x2.baseVal (ein SVGLength) liest und setzt man den im Attribut hinterlegten Wert. x2.animVal enthält den aktuellen, möglicherweise durch SMIL-Animationen veränderten Wert und kann nur gelesen werden.

Wie der Wert zu deuten ist, hängt von gradientUnits ab. Beim Standardwert objectBoundingBox bezieht er sich auf den Begrenzungsrahmen des gefüllten Elements (1 bzw. 100% steht für den rechten Rand). Bei userSpaceOnUse wird er als Koordinate im Benutzerkoordinatensystem gelesen. Fehlt das Attribut, gilt 100%.

Typische Einsatzfälle sind: die Richtung eines Verlaufs zur Laufzeit ändern (z. B. drehen), Gradienten dynamisch erzeugen oder die Geometrie eines vorhandenen Gradienten auslesen.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (veränderbares SVGLength mit dem Attributwert) und animVal (schreibgeschütztes SVGLength mit dem aktuellen animierten Wert).

Beispiele

x2 eines vorhandenen Gradienten auslesen

// HTML: <svg><defs><linearGradient id="verlauf" x1="0%" x2="80%">...</linearGradient></defs></svg>
const grad = document.getElementById('verlauf');
const { baseVal } = grad.x2;

console.log(baseVal.valueAsString);        // Text wie im Attribut
console.log(baseVal.valueInSpecifiedUnits); // Zahl ohne Einheit
console.log(baseVal.unitType === SVGLength.SVG_LENGTHTYPE_PERCENTAGE);

80% 80 true

Gradienten per Skript erzeugen und x2 setzen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');
const defs = svg.querySelector('defs') ?? svg.appendChild(document.createElementNS(SVG_NS, 'defs'));

const grad = document.createElementNS(SVG_NS, 'linearGradient');
grad.id = 'dynamisch';

// Vertikaler Verlauf: Endpunkt bei x=0 %, y=100 %
grad.x2.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 0);
grad.y2.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 100);

for (const [offset, color] of [['0%', 'gold'], ['100%', 'crimson']]) {
  const stop = document.createElementNS(SVG_NS, 'stop');
  stop.setAttribute('offset', offset);
  stop.setAttribute('stop-color', color);
  grad.append(stop);
}
defs.append(grad);
svg.querySelector('rect').setAttribute('fill', 'url(#dynamisch)');

console.log(grad.getAttribute('x2'));

0%

Verlaufsrichtung animiert drehen

const grad = document.getElementById('verlauf');
// Richtung im Einheitsquadrat der Bounding Box (0..1)
grad.setAttribute('gradientUnits', 'objectBoundingBox');

let winkel = 0;
const drehen = () => {
  const rad = (winkel * Math.PI) / 180;
  const dx = Math.cos(rad) / 2;
  const dy = Math.sin(rad) / 2;
  grad.x1.baseVal.value = 0.5 - dx;
  grad.y1.baseVal.value = 0.5 - dy;
  grad.x2.baseVal.value = 0.5 + dx;
  grad.y2.baseVal.value = 0.5 + dy;
  winkel = (winkel + 1) % 360;
  requestAnimationFrame(drehen);
};
requestAnimationFrame(drehen);

// Wichtig · Fallstricke

Nicht direkt zuweisen: grad.x2 = '50%' hat keine Wirkung, im Strict Mode wirft es einen TypeError. Ändern lässt sich der Wert über grad.x2.baseVal (value, valueAsString, newValueSpecifiedUnits()) oder über setAttribute('x2', …).
Prozentwerte und value: Bei Prozentangaben liefert baseVal.value den umgerechneten Wert in Benutzereinheiten, und dieser hängt vom Kontext ab. Für den Prozentwert selbst verwendet man valueInSpecifiedUnits oder valueAsString.
gradientUnits beachten: Bei objectBoundingBox meint x2="1" den rechten Rand, bei userSpaceOnUse dagegen 1 Pixel im Benutzerkoordinatensystem.
Vererbung über href: Wenn ein Gradient Attribute über href/xlink:href von einem anderen erbt, gibt x2 nur das Attribut des eigenen Elements wieder (bzw. den Standardwert 100%), nicht den geerbten Wert.
Richtiger Namensraum: Dynamisch erzeugte Elemente müssen mit createElementNS('http://www.w3.org/2000/svg', …) angelegt werden, sonst gibt es die Eigenschaft nicht.
Kompatibilität: Wird von allen modernen Browsern seit Langem unterstützt (Baseline).

Siehe auch

SVGLinearGradientElement SVGLinearGradientElement.x1 SVGLinearGradientElement.y1 SVGLinearGradientElement.y2 SVGAnimatedLength SVGLength SVGGradientElement.gradientUnits