SVGGradientElement.href — Eigenschaft · JavaScript-Referenz

Signatur

SVGGradientElement.href

Beschreibung

Die Eigenschaft href von SVGGradientElement (Basis von <linearGradient> und <radialGradient>) spiegelt das Attribut href bzw. das ältere xlink:href wider. Über dieses Attribut kann ein Verlauf auf einen anderen Verlauf verweisen und dessen Farbstopps (<stop>) sowie nicht explizit gesetzte Attribute wie gradientUnits oder spreadMethod übernehmen (erben).

Der Rückgabewert ist kein einfacher String, sondern ein SVGAnimatedString. Dessen baseVal enthält den im Markup gesetzten Wert (z. B. "#basis") und ist beschreibbar, animVal enthält den aktuell wirksamen, ggf. durch SMIL-Animation veränderten Wert und ist nur lesbar.

Typischer Einsatz: Man definiert einmal eine Farbpalette in einem Basisverlauf und erzeugt mehrere Varianten (andere Richtung, andere Koordinaten), die per href darauf verweisen. Per Skript lässt sich so zur Laufzeit die Palette eines Verlaufs austauschen, indem man href.baseVal ändert.

Rückgabewert

Typ

SVGAnimatedString

Beschreibung

Objekt mit baseVal (beschreibbarer Attributwert, z. B. "#palette", oder leerer String, wenn kein Attribut gesetzt ist) und animVal (schreibgeschützter, aktuell wirksamer Wert).

Beispiele

Verweis eines Verlaufs auslesen

// HTML:
// <svg width="0" height="0">
//   <defs>
//     <linearGradient id="palette">
//       <stop offset="0" stop-color="gold" />
//       <stop offset="1" stop-color="crimson" />
//     </linearGradient>
//     <linearGradient id="vertikal" href="#palette" x1="0" y1="0" x2="0" y2="1" />
//   </defs>
// </svg>

const grad = document.getElementById('vertikal');
console.log(grad.href instanceof SVGAnimatedString);
console.log(grad.href.baseVal);
console.log(grad.href.animVal);

true #palette #palette

Farbpalette zur Laufzeit austauschen

const svgNS = 'http://www.w3.org/2000/svg';
const defs = document.querySelector('svg defs');

// Zweite Palette erzeugen
const kalt = document.createElementNS(svgNS, 'linearGradient');
kalt.id = 'kalt';
for (const [offset, color] of [['0', 'skyblue'], ['1', 'navy']]) {
  const stop = document.createElementNS(svgNS, 'stop');
  stop.setAttribute('offset', offset);
  stop.setAttribute('stop-color', color);
  kalt.append(stop);
}
defs.append(kalt);

// Verweis umstellen: 'href' selbst ist readonly, baseVal nicht
const grad = document.getElementById('vertikal');
grad.href.baseVal = '#kalt';
console.log(grad.getAttribute('href'));

#kalt

Vererbungskette eines Verlaufs auflösen

const resolveChain = (gradient) => {
  const chain = [gradient.id];
  let current = gradient;
  while (current?.href?.baseVal) {
    const id = current.href.baseVal.replace(/^#/, '');
    if (chain.includes(id)) break; // Zyklus-Schutz
    current = document.getElementById(id);
    if (!(current instanceof SVGGradientElement)) break;
    chain.push(id);
  }
  return chain;
};

console.log(resolveChain(document.getElementById('vertikal')));

["vertikal", "palette"]

// Wichtig · Fallstricke

Nur die Eigenschaft ist schreibgeschützt: grad.href = '#x' hat keine Wirkung (im Strict Mode TypeError). Ändern Sie stattdessen grad.href.baseVal oder nutzen Sie setAttribute('href', …).
href vs. xlink:href: SVG 2 bevorzugt das einfache href; sind beide gesetzt, gewinnt href. Für ältere Software (z. B. Safari < 12, manche Grafikprogramme) kann xlink:href nötig sein – setzen per setAttributeNS('http://www.w3.org/1999/xlink', 'xlink:href', '#id').
Der Wert ist eine unaufgelöste Referenz (z. B. #palette), nicht das Zielelement. Zeigt er auf ein nicht existierendes Element oder auf ein Element eines anderen Typs, wird der Verweis ignoriert.
Geerbt werden Stopps nur, wenn der verweisende Verlauf keine eigenen <stop>-Kinder hat.
Zirkuläre Verweise sind ein Fehler; Browser brechen sie ab – eigener Code, der Ketten auflöst, sollte einen Zyklus-Schutz haben.
Die Eigenschaft stammt aus dem Mixin SVGURIReference und wird von allen aktuellen Browsern unterstützt.

Siehe auch

SVGGradientElement SVGLinearGradientElement SVGRadialGradientElement SVGAnimatedString SVGGradientElement.gradientUnits SVGGradientElement.spreadMethod Element.setAttributeNS()