SVGUseElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGUseElement extends SVGGraphicsElement

Beschreibung

SVGUseElement ist die DOM-Schnittstelle des SVG-Elements <use>. Das Element nimmt einen Knoten, auf den über href verwiesen wird (z. B. ein <symbol>, <g> oder <path>), und stellt eine Kopie davon an der eigenen Position dar. So lassen sich Grafiken einmal definieren und beliebig oft wiederverwenden, etwa bei Icon-Sprites, wiederholten Diagrammsymbolen oder Kartenmarkierungen.

Die Schnittstelle erbt von SVGGraphicsElement (also u. a. getBBox(), transform und getCTM()) und stellt über SVGURIReference zusätzlich diese Eigenschaften bereit:

href – ein SVGAnimatedString mit dem Verweis auf das Ziel, z. B. #icon-home, und nur lesbar.
x, y – SVGAnimatedLength, um wie viel die Kopie verschoben wird.
width, height – SVGAnimatedLength. Sie wirken sich nur aus, wenn das Ziel ein <svg> oder ein <symbol> ist.

Die kopierten Inhalte landen in einem geschlossenen, nutzerseitigen Shadow Tree. Daher kann man sie nicht direkt über das DOM verändern. Änderungen am Original werden automatisch in allen <use>-Instanzen übernommen. Die Instanzen lassen sich nur über geerbte CSS-Eigenschaften (z. B. fill: currentColor) oder über CSS-Custom-Properties gestalten.

Rückgabewert

Typ

SVGUseElement

Beschreibung

Instanzen erhält man z. B. über document.createElementNS('http://www.w3.org/2000/svg', 'use') oder über querySelector('use').

Beispiele

Icon aus einem Sprite dynamisch erzeugen

const SVG_NS = 'http://www.w3.org/2000/svg';

const createIcon = (id, size = 24) => {
  const svg = document.createElementNS(SVG_NS, 'svg');
  svg.setAttribute('width', size);
  svg.setAttribute('height', size);
  svg.setAttribute('aria-hidden', 'true');

  const use = document.createElementNS(SVG_NS, 'use');
  // Modernes href statt xlink:href
  use.setAttribute('href', `#${id}`);
  svg.append(use);
  return svg;
};

const icon = createIcon('icon-home');
document.querySelector('button.home').prepend(icon);
console.log(icon.firstElementChild instanceof SVGUseElement);

true

Position und Verweis über die animierten Eigenschaften lesen

// <svg><defs><circle id="dot" r="5"/></defs>
//   <use id="marker" href="#dot" x="40" y="20"/></svg>
const marker = document.querySelector('#marker');

console.log(marker.href.baseVal);      // Verweis-Ziel
console.log(marker.x.baseVal.value);   // x in Benutzereinheiten
console.log(marker.y.baseVal.value);

// Position direkt über SVGLength ändern
marker.x.baseVal.value = 100;
console.log(marker.getAttribute('x'));

#dot 40 20 100

Icon beim Umschalten austauschen (z. B. Play/Pause)

const toggle = document.querySelector('#player-toggle');
const use = toggle.querySelector('use');

toggle.addEventListener('click', () => {
  const playing = toggle.getAttribute('aria-pressed') === 'true';
  toggle.setAttribute('aria-pressed', String(!playing));
  // href.baseVal ist beschreibbar und aktualisiert das Attribut
  use.href.baseVal = playing ? '#icon-play' : '#icon-pause';
});

// Wichtig · Fallstricke

Namensraum: Elemente mit document.createElement('use') zu erzeugen funktioniert nicht, denn dabei entsteht ein HTMLUnknownElement. Immer createElementNS('http://www.w3.org/2000/svg', 'use') verwenden.
xlink:href ist veraltet. Stattdessen href verwenden. Aktuelle Browser unterstützen es alle. Nur sehr alte Safari-Versionen (vor 12.1) brauchen noch xlink:href, das man mit setAttributeNS('http://www.w3.org/1999/xlink', 'xlink:href', …) setzt.
Same-Origin-Beschränkung: Verweise auf externe Dateien (sprite.svg#icon) müssen vom gleichen Ursprung stammen. Über andere Ursprünge werden sie auch mit CORS-Headern nicht geladen. data:-URLs werden in aktuellen Browsern aus Sicherheitsgründen blockiert (XSS-Vektor).
Shadow Tree: Die kopierten Elemente sind über das DOM nicht erreichbar. instanceRoot und animatedInstanceRoot wurden aus SVG 2 entfernt und werden praktisch nicht mehr unterstützt. Ereignisse aus der Kopie kommen mit dem <use>-Element als event.target an.
Gestaltung: CSS-Selektoren von außen erreichen die Kopie nicht. Man kann nur Werte vererben, z. B. über fill="currentColor" im Original oder var(--icon-color).
Zeigt ein Verweis zirkulär auf sich selbst oder auf einen Vorfahren, wird nichts dargestellt.

Siehe auch

SVGSetElement SVGAElement SVGDescElement SVGElement SVGGElement