SVGStopElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGStopElement extends SVGElement

Beschreibung

SVGStopElement ist die DOM-Schnittstelle für das Element <stop>. Ein <stop> legt fest, welche Farbe (stop-color) und welche Deckkraft (stop-opacity) ein Verlauf an einer bestimmten Position (offset) hat. Stopps stehen immer als Kindelemente in einem <linearGradient> oder <radialGradient>.

Die Schnittstelle erbt alle Eigenschaften und Methoden von SVGElement, Element, Node und EventTarget. Eigene Eigenschaft ist nur offset (nur lesbar): ein SVGAnimatedNumber, das die Position des Stopps als Zahl zwischen 0 und 1 enthält. Über offset.baseVal liest und setzt man den Grundwert, offset.animVal liefert den aktuellen (ggf. per SMIL animierten) Wert.

Man braucht die Schnittstelle vor allem, wenn Verläufe per JavaScript erzeugt oder verändert werden sollen, z. B. für dynamische Diagramme, Fortschrittsbalken oder animierte Hintergründe. Farbe und Deckkraft sind keine eigenen DOM-Eigenschaften, sondern Präsentationsattribute bzw. CSS-Eigenschaften. Man setzt sie über setAttribute() oder element.style.

Parameter

Name	Typ	Default	Beschreibung
$offset	SVGAnimatedNumber	0	Nur lesbare Eigenschaft: Position des Stopps im Verlauf. `offset.baseVal` ist eine Zahl von `0` bis `1`; Prozentangaben im Attribut (`"50%"`) werden in diese Zahl umgerechnet (`0.5`).

Rückgabewert

Typ

SVGStopElement

Beschreibung

Instanzen entstehen über document.createElementNS("http://www.w3.org/2000/svg", "stop") oder durch Abfragen vorhandener <stop>-Elemente im DOM.

Beispiele

Verlauf mit Stopps dynamisch erzeugen

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

const defs = document.createElementNS(SVG_NS, "defs");
const gradient = document.createElementNS(SVG_NS, "linearGradient");
gradient.id = "verlauf";

// Farbstopps anlegen
const stopps = [
  { offset: "0%", color: "#ff6b6b" },
  { offset: "100%", color: "#4dabf7" }
];
for (const { offset, color } of stopps) {
  const stop = document.createElementNS(SVG_NS, "stop");
  stop.setAttribute("offset", offset);
  stop.setAttribute("stop-color", color);
  gradient.append(stop);
}

defs.append(gradient);
const rect = document.createElementNS(SVG_NS, "rect");
rect.setAttribute("width", "200");
rect.setAttribute("height", "50");
rect.setAttribute("fill", "url(#verlauf)");
svg.append(defs, rect);
document.body.append(svg);

const ersterStopp = gradient.querySelector("stop");
console.log(ersterStopp instanceof SVGStopElement);

true

Offset lesen und über baseVal ändern

// <stop id="mitte" offset="50%" stop-color="gold" /> im Dokument
const stop = document.getElementById("mitte");

console.log(stop.offset.baseVal); // Prozent wird zu Zahl

stop.offset.baseVal = 0.25;
console.log(stop.getAttribute("offset"));

0.5 0.25

Fortschrittsbalken mit hartem Farbwechsel

// <linearGradient id="fortschritt">
//   <stop offset="0" stop-color="#40c057" />
//   <stop offset="0" stop-color="#dee2e6" />
// </linearGradient>
const [voll, leer] = document.querySelectorAll("#fortschritt stop");

const setzeFortschritt = (anteil) => {
  const wert = Math.min(Math.max(anteil, 0), 1);
  voll.offset.baseVal = wert;
  leer.offset.baseVal = wert;
};

setzeFortschritt(0.7);
console.log(voll.offset.baseVal);

0.699999988079071

Farbe und Deckkraft per CSS setzen

const stop = document.querySelector("#verlauf stop");

// stop-color ist keine DOM-Eigenschaft, sondern eine CSS-Eigenschaft
stop.style.stopColor = "rebeccapurple";
stop.style.stopOpacity = "0.6";

console.log(getComputedStyle(stop).stopOpacity);

0.6

// Wichtig · Fallstricke

Namensraum: Stopps muss man mit createElementNS("http://www.w3.org/2000/svg", "stop") erzeugen. document.createElement("stop") liefert ein HTMLUnknownElement und hat keine Wirkung.
Genauigkeit: offset.baseVal ist eine 32-Bit-Gleitkommazahl. Werte wie 0.7 werden deshalb als 0.699999988… zurückgelesen.
Wertebereich: Offsets unter 0 oder über 1 werden beim Zeichnen auf diesen Bereich begrenzt. Ist ein Offset kleiner als der des vorigen Stopps, wird er auf dessen Wert angehoben. So entstehen harte Farbkanten.
Keine eigenen Farb-Eigenschaften: stop-color und stop-opacity setzt man über Attribute oder CSS. CSS-Regeln haben Vorrang vor Präsentationsattributen.
Kompatibilität: Die Schnittstelle wird von allen modernen Browsern unterstützt. Das Attribut offset lässt sich per SMIL (<animate>) animieren, der animierte Wert steht dann in offset.animVal.

Siehe auch

SVGSVGElement SVGSetElement SVGStyleElement SVGAElement SVGDefsElement