Signatur
Beschreibung
Die Eigenschaft href des SVGImageElement-Interfaces stammt aus dem Mixin SVGURIReference. Sie gibt die Bildquelle eines <image>-Elements in SVG zurück, allerdings nicht als einfachen String, sondern als SVGAnimatedString-Objekt.
Die Eigenschaft selbst ist schreibgeschützt: Das Objekt kann man nicht durch ein anderes ersetzen. Die URL lässt sich trotzdem ändern, und zwar über href.baseVal. Diese Eigenschaft ist beschreibbar und entspricht direkt dem Attributwert. href.animVal enthält den aktuell animierten Wert, zum Beispiel während einer SMIL-Animation mit <set> oder <animate>. Ohne laufende Animation ist er gleich baseVal.
Nach SVG 2 spiegelt die Eigenschaft das moderne Attribut href wider. Fehlt es, greift sie auf das alte xlink:href zurück. Brauchbar ist das, wenn man Bildquellen in SVG-Grafiken per Skript lesen oder austauschen will, zum Beispiel für Themenwechsel, Vorschaubilder oder Lazy Loading in Diagrammen.
Rückgabewert
baseVal (string, beschreibbar: der Attributwert) und animVal (string, schreibgeschützt: der aktuell animierte Wert).Beispiele
Bildquelle eines SVG-image auslesen
// <svg><image id="logo" href="/img/logo.png" width="100" height="50"/></svg>
const img = document.querySelector('#logo');
console.log(img.href instanceof SVGAnimatedString);
console.log(img.href.baseVal);
console.log(img.href.animVal);Bild per Skript austauschen (z. B. Dark Mode)
const logo = document.querySelector('#logo');
const setTheme = (dark) => {
// Nicht img.href = '...' (wirkungslos), sondern baseVal setzen
logo.href.baseVal = dark ? '/img/logo-dark.png' : '/img/logo.png';
};
const mq = window.matchMedia('(prefers-color-scheme: dark)');
setTheme(mq.matches);
mq.addEventListener('change', (e) => setTheme(e.matches));
console.log(logo.getAttribute('href'));image-Element dynamisch erzeugen und auf das Laden warten
const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');
const loadSvgImage = (url, w, h) => new Promise((resolve, reject) => {
const image = document.createElementNS(SVG_NS, 'image');
image.setAttribute('width', w);
image.setAttribute('height', h);
image.addEventListener('load', () => resolve(image), { once: true });
image.addEventListener('error', () => reject(new Error(`Fehler: ${url}`)), { once: true });
image.href.baseVal = url;
svg.append(image);
});
const image = await loadSvgImage('/img/karte.png', 300, 200);
console.log('Geladen:', image.href.baseVal);Altes xlink:href-Attribut auslesen
// <image id="alt" xlink:href="foto.jpg" width="80" height="80"/>
const XLINK_NS = 'http://www.w3.org/1999/xlink';
const alt = document.querySelector('#alt');
console.log(alt.href.baseVal);
console.log(alt.getAttributeNS(XLINK_NS, 'href'));// Wichtig · Fallstricke
- Häufiger Fehler:
img.href = 'neu.png'bewirkt nichts (im Strict Mode wird einTypeErrorgeworfen), weil die Eigenschaft schreibgeschützt ist. Setze stattdessenimg.href.baseValoder nutzesetAttribute('href', …). - Anders als bei
HTMLImageElement.srcwird der Wert nicht zu einer absoluten URL aufgelöst:baseValliefert den Attributwert genau so, wie er im Markup steht. - Ein
SVGAnimatedStringwird bei Ausgabe oder Vergleich nicht automatisch in einen String umgewandelt.img.href === '/img/logo.png'ist deshalb immerfalse. xlink:hrefgilt seit SVG 2 als veraltet. Für neuen Code verwendest du nurhref. Sehr alte Browser (z. B. Safari vor 12) kennen nurxlink:href. Sind beide Attribute gesetzt, hathrefVorrang.- Die Eigenschaft wird von allen modernen Browsern unterstützt. Bilder aus anderen Quellen unterliegen der CSP-Direktive
img-src. Wird das SVG in ein<canvas>gezeichnet, gelten CORS-Regeln, und ein fremdes Bild kann die Canvas „verunreinigen“ (tainted canvas).