Signatur
Beschreibung
Die Eigenschaft offset des SVGStopElement steht für das Attribut offset eines <stop>-Elements. Dieses Attribut legt fest, an welcher Stelle eines <linearGradient> oder <radialGradient> ein Farbstopp liegt. Der Wert reicht von 0 (Anfang des Verlaufs) bis 1 (Ende).
Zurückgegeben wird kein einfacher Zahlenwert, sondern ein SVGAnimatedNumber-Objekt. Über offset.baseVal liest und setzt man den im Attribut hinterlegten Grundwert. offset.animVal liefert den aktuellen Wert, also einschließlich einer möglichen SMIL-Animation (z. B. über <animate attributeName="offset">), und lässt sich nur lesen.
Steht im Attribut ein Prozentwert wie offset="50%", wird er in eine Zahl umgerechnet: baseVal liefert dann 0.5. Die Eigenschaft eignet sich gut für dynamische Verläufe, etwa Fortschrittsbalken, Hover-Effekte oder Diagramme, bei denen sich die Farbstopps mit JavaScript verschieben lassen, ohne dass man Attribut-Strings selbst zusammensetzen muss.
Rückgabewert
baseVal (number, les- und schreibbar, entspricht dem Attribut) und animVal (number, nur lesbar, aktueller animierter Wert). Der Wert ist eine Zahl, die normalerweise zwischen 0 und 1 liegt.Beispiele
Offset eines Farbstopps auslesen
// <svg><defs><linearGradient id="verlauf">
// <stop offset="0" stop-color="gold"/>
// <stop offset="75%" stop-color="crimson"/>
// </linearGradient></defs></svg>
const stops = document.querySelectorAll('#verlauf stop');
stops.forEach((stop, i) => {
console.log(`Stopp ${i}: ${stop.offset.baseVal}`);
});Fortschrittsbalken mit hartem Farbübergang
// Zwei Stopps an derselben Position erzeugen eine scharfe Kante
const [fillEnd, emptyStart] = document.querySelectorAll('#progress stop.edge');
const setProgress = (percent) => {
const value = Math.min(Math.max(percent / 100, 0), 1);
fillEnd.offset.baseVal = value;
emptyStart.offset.baseVal = value;
};
setProgress(42);
console.log(fillEnd.getAttribute('offset'));Stopp neu anlegen und positionieren
const SVG_NS = 'http://www.w3.org/2000/svg';
const gradient = document.querySelector('#verlauf');
const stop = document.createElementNS(SVG_NS, 'stop');
stop.setAttribute('stop-color', 'royalblue');
stop.offset.baseVal = 0.5; // entspricht offset="0.5"
gradient.append(stop);
console.log(stop instanceof SVGStopElement, stop.offset.animVal);Animierten Wert mit dem Grundwert vergleichen
// <stop id="s" offset="0.2" stop-color="teal">
// <animate attributeName="offset" from="0.2" to="0.8" dur="2s" repeatCount="indefinite"/>
// </stop>
const stop = document.getElementById('s');
setInterval(() => {
const { baseVal, animVal } = stop.offset;
console.log(`Basis: ${baseVal}, aktuell: ${animVal.toFixed(2)}`);
}, 500);// Wichtig · Fallstricke
- Schreibgeschützt heißt hier: Die Eigenschaft
offsetselbst lässt sich nicht neu zuweisen.stop.offset = 0.5hat keine Wirkung und wirft im Strict Mode einenTypeError. Schreiben Sie stattdessenstop.offset.baseVal = 0.5. - Prozentwerte:
baseValgibt immer einen Bruchteil zurück ("30%"wird zu0.3). Setzen SiebaseVal, schreibt der Browser eine reine Zahl ins Attribut, nicht die Prozentform. - Wertebereich: Werte unter
0oder über1werden beim Zeichnen auf den Bereich 0–1 begrenzt. Ist ein Offset kleiner als der des vorherigen Stopps, wird er beim Zeichnen auf diesen Wert angehoben. Begrenzen Sie die Werte am besten schon im eigenen Code. - CSS kann den Wert nicht ändern:
offsetist keine CSS-Eigenschaft. Anders alsstop-colorundstop-opacitylässt es sich weder per Stylesheet setzen noch mit CSS-Transitions animieren. Möglich sind nur SMIL oder JavaScript, etwa mitrequestAnimationFrame. - Namensraum: Dynamisch erzeugte Stopps müssen mit
document.createElementNS('http://www.w3.org/2000/svg', 'stop')angelegt werden.createElement('stop')erzeugt keinSVGStopElement, undoffsetist dannundefined. - Kompatibilität: Wird von allen aktuellen Browsern seit Langem unterstützt. In Node.js gibt es sie nur mit einer DOM-Umgebung wie jsdom, und dort ist die SVG-Unterstützung teilweise lückenhaft.