SVGGradientElement.spreadMethod — Eigenschaft · JavaScript-Referenz

Signatur

SVGGradientElement.spreadMethod

Beschreibung

Die Eigenschaft spreadMethod der Schnittstelle SVGGradientElement gibt das Attribut spreadMethod eines <linearGradient>- oder <radialGradient>-Elements wieder. Das Attribut legt fest, wie der Verlauf die Fläche außerhalb seines definierten Bereichs füllt, also vor dem ersten und nach dem letzten <stop>.

Zurückgegeben wird ein SVGAnimatedEnumeration-Objekt. Dessen Eigenschaft baseVal enthält den eingestellten Wert und lässt sich beschreiben. animVal ist schreibgeschützt und enthält den aktuellen Wert, gegebenenfalls nach einer SMIL-Animation. Die Werte sind Zahlen und entsprechen den Konstanten von SVGGradientElement:

SVG_SPREADMETHOD_UNKNOWN (0): unbekannter oder ungültiger Wert
SVG_SPREADMETHOD_PAD (1): Die Randfarben werden bis zum Rand der Fläche fortgesetzt (Standardwert).
SVG_SPREADMETHOD_REFLECT (2): Der Verlauf wird abwechselnd gespiegelt wiederholt.
SVG_SPREADMETHOD_REPEAT (3): Der Verlauf wird in derselben Richtung wiederholt.

Die Eigenschaft ist nützlich, wenn du das Verhalten eines Verlaufs per Skript auslesen oder ändern willst, etwa für interaktive Grafiken, Editoren oder Themes. Du kannst dem Objekt selbst nichts zuweisen. Um den Wert zu ändern, setzt du spreadMethod.baseVal oder rufst setAttribute('spreadMethod', …) auf.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Objekt mit baseVal (beschreibbar) und animVal (schreibgeschützt). Beide enthalten einen der Zahlenwerte 0–3, die den Konstanten SVG_SPREADMETHOD_* entsprechen.

Beispiele

Aktuelle Spread-Methode auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const gradient = document.createElementNS(svgNS, 'linearGradient');
gradient.setAttribute('spreadMethod', 'reflect');

const { baseVal } = gradient.spreadMethod;
console.log(baseVal);
console.log(baseVal === SVGGradientElement.SVG_SPREADMETHOD_REFLECT);

2 true

Zahlenwert in lesbaren Namen umwandeln

const namen = {
  [SVGGradientElement.SVG_SPREADMETHOD_UNKNOWN]: 'unknown',
  [SVGGradientElement.SVG_SPREADMETHOD_PAD]: 'pad',
  [SVGGradientElement.SVG_SPREADMETHOD_REFLECT]: 'reflect',
  [SVGGradientElement.SVG_SPREADMETHOD_REPEAT]: 'repeat'
};

// Ohne Attribut gilt der Standardwert "pad"
const grad = document.createElementNS('http://www.w3.org/2000/svg', 'radialGradient');
console.log(namen[grad.spreadMethod.baseVal]);

pad

Spread-Methode per Button umschalten

// HTML: <svg><defs><linearGradient id="verlauf" x1="0" x2="0.3">
//   <stop offset="0" stop-color="tomato"/><stop offset="1" stop-color="gold"/>
// </linearGradient></defs><rect width="300" height="80" fill="url(#verlauf)"/></svg>
// <button id="umschalten">Umschalten</button>
const verlauf = document.querySelector('#verlauf');
const reihenfolge = [
  SVGGradientElement.SVG_SPREADMETHOD_PAD,
  SVGGradientElement.SVG_SPREADMETHOD_REFLECT,
  SVGGradientElement.SVG_SPREADMETHOD_REPEAT
];

document.querySelector('#umschalten').addEventListener('click', () => {
  const aktuell = reihenfolge.indexOf(verlauf.spreadMethod.baseVal);
  const naechster = reihenfolge[(aktuell + 1) % reihenfolge.length];
  verlauf.spreadMethod.baseVal = naechster; // aktualisiert auch das Attribut
  console.log(verlauf.getAttribute('spreadMethod'));
});

reflect (beim ersten Klick)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie gradient.spreadMethod = 2 hat keine Wirkung und wirft im Strict Mode einen TypeError. Ändere stattdessen spreadMethod.baseVal.
Zahlen statt Zeichenketten: baseVal enthält eine Zahl und nicht 'pad', 'reflect' oder 'repeat'. Für Vergleiche solltest du die Konstanten SVG_SPREADMETHOD_* verwenden.
Wird baseVal auf 0 (UNKNOWN) oder einen Wert außerhalb des gültigen Bereichs gesetzt, wirft der Browser einen TypeError. Ältere Browser werfen in diesem Fall einen DOMException.
Die Spread-Methode ist nur sichtbar, wenn der Verlauf die Form nicht vollständig abdeckt, etwa bei x1/x2 unter 100 % oder einem kleinen r. Andernfalls sieht jede Methode gleich aus.
Bei Verläufen, die über href von einem anderen Verlauf erben, liefert baseVal nur den Attributwert des eigenen Elements und nicht den geerbten Wert.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Ältere Safari-Versionen haben reflect und repeat teilweise fehlerhaft dargestellt.

Siehe auch

SVGGradientElement SVGGradientElement.gradientUnits SVGGradientElement.gradientTransform SVGAnimatedEnumeration SVGLinearGradientElement SVGRadialGradientElement