SVGUseElement.href — Eigenschaft · JavaScript-Referenz

Signatur

SVGUseElement.href

Beschreibung

Die Eigenschaft href der Schnittstelle SVGUseElement spiegelt das Attribut href (bzw. das ältere xlink:href) eines <use>-Elements wider. Dieses Attribut legt fest, welches Element oder Symbol das <use>-Element klont und rendert, z. B. #icon-home oder sprite.svg#icon-home.

Der Rückgabewert ist kein einfacher String, sondern ein SVGAnimatedString-Objekt. Es hat zwei Eigenschaften: baseVal enthält den im Attribut gesetzten Wert und ist beschreibbar, animVal enthält den aktuell animierten Wert (etwa durch SMIL-<set>) und ist schreibgeschützt. „Schreibgeschützt“ gilt also nur für die Eigenschaft href selbst. Das Objekt lässt sich nicht ersetzen, href.baseVal kann man aber ändern.

Typischer Einsatz sind SVG-Icon-Sprites: Mit use.href.baseVal = '#icon-close' tauscht man zur Laufzeit ein Icon aus, ohne das DOM neu aufzubauen. Alternativ setzt man das Attribut direkt mit setAttribute('href', …). Das Ergebnis ist dasselbe.

Rückgabewert

Typ

SVGAnimatedString

Beschreibung

Ein Objekt mit baseVal (beschreibbarer Attributwert als string) und animVal (schreibgeschützter, aktuell animierter Wert als string).

Beispiele

Referenziertes Symbol auslesen

// <svg><symbol id="icon-home" viewBox="0 0 24 24"><path d="M3 12l9-9 9 9"/></symbol>
//      <use id="icon" href="#icon-home"/></svg>
const use = document.querySelector('#icon');
console.log(use.href instanceof SVGAnimatedString);
console.log(use.href.baseVal);
console.log(use.href.animVal);

true #icon-home #icon-home

Icon aus einem Sprite zur Laufzeit austauschen

const button = document.querySelector('#menu-toggle');
const icon = button.querySelector('use');

button.addEventListener('click', () => {
  const open = button.getAttribute('aria-expanded') === 'true';
  button.setAttribute('aria-expanded', String(!open));
  // baseVal ist beschreibbar, href selbst nicht
  icon.href.baseVal = open ? '#icon-menu' : '#icon-close';
});

use-Element per Skript erzeugen

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

const use = document.createElementNS(SVG_NS, 'use');
use.href.baseVal = '/img/sprite.svg#icon-star';
svg.append(use);
document.body.append(svg);

console.log(use.getAttribute('href'));

/img/sprite.svg#icon-star

Fallback auf xlink:href prüfen

const XLINK_NS = 'http://www.w3.org/1999/xlink';
const getUseTarget = (use) =>
  use.getAttribute('href') ?? use.getAttributeNS(XLINK_NS, 'href');

const use = document.querySelector('use');
console.log(getUseTarget(use), use.href.baseVal);

#icon-home #icon-home

// Wichtig · Fallstricke

Kein String: use.href liefert ein SVGAnimatedString. Eine Zuweisung wie use.href = '#x' wird ignoriert und wirft im strikten Modus einen TypeError. Schreiben Sie stattdessen in use.href.baseVal.
Nicht mit HTMLAnchorElement.href verwechseln: Anders als bei HTML-Links wird der Wert nicht zu einer absoluten URL aufgelöst. baseVal enthält den Attributwert unverändert.
href vs. xlink:href: xlink:href gilt seit SVG 2 als veraltet. Sind beide Attribute gesetzt, hat href Vorrang. Ganz alte Browser (etwa Safari < 12) verstehen nur xlink:href.
Externe Referenzen: <use> lädt externe SVG-Dateien nur vom selben Ursprung (Same-Origin). Ursprungsübergreifende Referenzen werden blockiert, CORS-Header helfen hier nicht. data:-URLs werden von aktuellen Browsern aus Sicherheitsgründen ebenfalls abgelehnt.
Sicherheit: Wenn Sie Werte aus Benutzereingaben in baseVal schreiben, prüfen Sie sie vorher, z. B. mit einer Whitelist erlaubter Fragment-IDs. So lassen sich keine fremden Inhalte einbinden.
Der geklonte Inhalt liegt in einem geschlossenen Shadow-Baum. Das Ändern von href ersetzt ihn vollständig, Event-Listener auf den Klonen gehen dabei verloren.

Siehe auch

SVGUseElement SVGAnimatedString SVGUseElement.x SVGAElement.href Element.setAttribute() Document.createElementNS() PromiseRejectionEvent.reason