SVGGradientElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGGradientElement extends SVGElement

Beschreibung

SVGGradientElement ist die gemeinsame Basis der Interfaces SVGLinearGradientElement (<linearGradient>) und SVGRadialGradientElement (<radialGradient>). Instanzen des Interfaces selbst erzeugt man nie direkt. Man bekommt immer eines der beiden konkreten Elemente, die alle hier definierten Eigenschaften erben.

Das Interface stellt drei animierbare Eigenschaften bereit:

gradientUnits (SVGAnimatedEnumeration): Koordinatensystem des Verlaufs, entweder userSpaceOnUse oder objectBoundingBox.
gradientTransform (SVGAnimatedTransformList): zusätzliche Transformationen, zum Beispiel eine Drehung des Verlaufs.
spreadMethod (SVGAnimatedEnumeration): legt fest, was außerhalb des Verlaufsbereichs passiert (pad, reflect oder repeat).

Über SVGURIReference kommt außerdem href hinzu. Damit kann ein Verlauf die Stopps und Attribute eines anderen Verlaufs übernehmen. Die numerischen Konstanten SVG_SPREADMETHOD_UNKNOWN (0), SVG_SPREADMETHOD_PAD (1), SVG_SPREADMETHOD_REFLECT (2) und SVG_SPREADMETHOD_REPEAT (3) stehen direkt am Interface zur Verfügung.

Das Interface braucht man, wenn man Verläufe per Skript liest oder dynamisch verändert, etwa für Themes, Diagramme oder Animationen. Mit instanceof SVGGradientElement lassen sich außerdem beide Verlaufsarten mit einer einzigen Prüfung erkennen.

Rückgabewert

Typ

SVGGradientElement

Beschreibung

Wird nicht direkt erzeugt. Man erhält immer eine Instanz von SVGLinearGradientElement oder SVGRadialGradientElement.

Beispiele

Verlauf per Skript erzeugen (Instanziierung über createElementNS)

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

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

[['0%', '#0af'], ['100%', '#004']].forEach(([offset, color]) => {
  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', '100');
rect.setAttribute('fill', 'url(#blauVerlauf)');
svg.append(defs, rect);
document.body.append(svg);

console.log(grad instanceof SVGGradientElement);
console.log(grad instanceof SVGLinearGradientElement);

true true

spreadMethod lesen und auf „reflect“ umstellen

const grad = document.querySelector('#blauVerlauf');
const namen = ['unknown', 'pad', 'reflect', 'repeat'];

console.log('Vorher:', namen[grad.spreadMethod.baseVal]);

// Zuweisung über die Konstante am Interface
grad.spreadMethod.baseVal = SVGGradientElement.SVG_SPREADMETHOD_REFLECT;
// Gleichwertig: grad.setAttribute('spreadMethod', 'reflect');

console.log('Nachher:', namen[grad.spreadMethod.baseVal]);
console.log(grad.getAttribute('spreadMethod'));

Vorher: pad Nachher: reflect reflect

Verlauf drehen über gradientTransform

const svg = document.querySelector('svg');
const grad = document.querySelector('#blauVerlauf');

const rotation = svg.createSVGTransform();
rotation.setRotate(45, 0.5, 0.5);

const liste = grad.gradientTransform.baseVal;
liste.clear();
liste.appendItem(rotation);

console.log(grad.getAttribute('gradientTransform'));
console.log(grad.gradientUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX);

rotate(45 0.5 0.5) true

Alle Verläufe eines Dokuments einheitlich behandeln

const verlaeufe = [...document.querySelectorAll('linearGradient, radialGradient')]
  .filter((el) => el instanceof SVGGradientElement);

verlaeufe.forEach((g) => {
  g.setAttribute('spreadMethod', 'repeat');
  console.log(g.id, g.constructor.name, g.stops?.length ?? g.querySelectorAll('stop').length);
});

blauVerlauf SVGLinearGradientElement 2

// Wichtig · Fallstricke

Namensraum: SVG-Elemente müssen mit document.createElementNS('http://www.w3.org/2000/svg', …) erzeugt werden. document.createElement('linearGradient') liefert nur ein HTMLUnknownElement, das nicht als Verlauf funktioniert.
Nur Lesezugriff auf das Objekt: gradientUnits, spreadMethod und gradientTransform sind animierte Objekte, keine einfachen Strings. Ändern lassen sie sich über .baseVal. Den aktuellen, eventuell per SMIL animierten Wert liefert .animVal.
Standardwerte: Ohne Attribut gelten gradientUnits="objectBoundingBox" und spreadMethod="pad". Bei objectBoundingBox beziehen sich Koordinaten auf den Bereich 0–1 des gefüllten Elements, und ein Transformationszentrum liegt entsprechend bei 0.5 0.5.
href-Vererbung: Enthält ein Verlauf keine eigenen <stop>-Elemente, übernimmt er die Stopps des Verlaufs, auf den href verweist. Das ältere xlink:href ist veraltet, wird aber weiterhin unterstützt.
Doppelte IDs: Verweise wie fill="url(#id)" gelten für das ganze Dokument. Sind mehrere Inline-SVGs mit gleicher ID eingebunden, wird der erste Treffer verwendet.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Nur wenige, ältere Engines setzen spreadMethod mit reflect/repeat bei radialen Verläufen nicht zuverlässig um.

Siehe auch

SVGGraphicsElement SVGRectElement SVGAnimateElement SVGDefsElement SVGDescElement