SVGLinearGradientElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGLinearGradientElement extends SVGGradientElement

Beschreibung

Die Schnittstelle SVGLinearGradientElement steht im DOM für ein <linearGradient>-Element. Ein linearer Verlauf verläuft entlang eines Vektors vom Punkt (x1, y1) zum Punkt (x2, y2). Seine Farbstufen werden durch untergeordnete <stop>-Elemente festgelegt. Formen verweisen per fill="url(#id)" oder stroke="url(#id)" auf den Verlauf.

Die Schnittstelle erbt von SVGGradientElement. Von dort kommen gradientUnits, gradientTransform, spreadMethod und href. Selbst ergänzt sie nur vier schreibgeschützte Eigenschaften vom Typ SVGAnimatedLength:

x1: x-Koordinate des Startpunkts (Standardwert 0%)
y1: y-Koordinate des Startpunkts (Standardwert 0%)
x2: x-Koordinate des Endpunkts (Standardwert 100%)
y2: y-Koordinate des Endpunkts (Standardwert 0%)

Die Schnittstelle ist nützlich, wenn man Verläufe per Skript erzeugen, ihre Richtung dynamisch ändern oder animieren will, etwa für Fortschrittsbalken, Diagramme oder Hover-Effekte. Jede Eigenschaft hat einen baseVal, den man ändern kann, und einen animVal, der nur gelesen werden kann und den aktuellen, eventuell per SMIL animierten Wert enthält.

Rückgabewert

Typ

SVGLinearGradientElement

Beschreibung

Bekommt man über document.createElementNS("http://www.w3.org/2000/svg", "linearGradient") oder durch Abfrage eines vorhandenen <linearGradient>-Elements. Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Verlauf per Skript erzeugen und anwenden

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('width', '200');
svg.setAttribute('height', '60');

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

// Farbstufen hinzufügen
for (const [offset, color] of [['0%', '#1e90ff'], ['100%', '#00c9a7']]) {
  const stop = document.createElementNS(SVG_NS, 'stop');
  stop.setAttribute('offset', offset);
  stop.setAttribute('stop-color', color);
  grad.append(stop);
}

defs.append(grad);
const rect = document.createElementNS(SVG_NS, 'rect');
rect.setAttribute('width', '200');
rect.setAttribute('height', '60');
rect.setAttribute('fill', 'url(#blauVerlauf)');
svg.append(defs, rect);
document.body.append(svg);

console.log(grad instanceof SVGLinearGradientElement);
console.log(grad.x2.baseVal.valueAsString);

true 100%

Richtung des Verlaufs ändern (vertikal)

// <linearGradient id="g"> existiert bereits im Dokument
const grad = document.querySelector('#g');

// von oben nach unten: (0%,0%) -> (0%,100%)
grad.x2.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 0);
grad.y2.baseVal.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PERCENTAGE, 100);

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

0% 100%

Verlauf rotieren lassen

const grad = document.querySelector('#g');
let winkel = 0;

const drehen = () => {
  winkel = (winkel + 1) % 360;
  const rad = (winkel * Math.PI) / 180;
  // Vektor um den Mittelpunkt (50%, 50%) drehen
  const dx = Math.cos(rad) * 50;
  const dy = Math.sin(rad) * 50;
  grad.x1.baseVal.valueAsString = `${50 - dx}%`;
  grad.y1.baseVal.valueAsString = `${50 - dy}%`;
  grad.x2.baseVal.valueAsString = `${50 + dx}%`;
  grad.y2.baseVal.valueAsString = `${50 + dy}%`;
  requestAnimationFrame(drehen);
};
requestAnimationFrame(drehen);

// Wichtig · Fallstricke

Namensraum: Mit document.createElement('linearGradient') entsteht ein wirkungsloses HTMLUnknownElement. Man muss createElementNS('http://www.w3.org/2000/svg', …) verwenden.
Nur lesbare Eigenschaften: grad.x1 = '10%' bewirkt nichts (im Strict Mode gibt es einen TypeError). Werte ändert man über x1.baseVal.value, x1.baseVal.valueAsString oder setAttribute('x1', …).
Einheiten: Bei gradientUnits="objectBoundingBox" (der Standardwert) beziehen sich die Koordinaten auf den Begrenzungsrahmen der Form. Bei Formen ohne Breite oder Höhe, etwa einer waagerechten <line>, wird der Verlauf deshalb nicht gezeichnet. Hier hilft gradientUnits="userSpaceOnUse".
Eindeutige IDs: Stehen mehrere Inline-SVGs auf einer Seite, führen doppelte Verlaufs-IDs dazu, dass der falsche Verlauf benutzt wird. Das passiert leicht bei wiederverwendeten Komponenten.
Kompatibilität: Wird von allen modernen Browsern unterstützt. SMIL-Animationen (animVal) gehen ebenfalls überall, CSS kann die Attribute x1–y2 aber nicht animieren.

Siehe auch

SVGRadialGradientElement SVGGradientElement SVGAnimationElement SVGDiscardElement SVGFEMergeElement