SVGSymbolElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGSymbolElement extends SVGGraphicsElement

Beschreibung

SVGSymbolElement ist die DOM-Schnittstelle des Elements <symbol>. Ein Symbol legt eine Grafikvorlage fest, etwa ein Icon, die selbst nicht dargestellt wird. Sichtbar wird sie erst, wenn ein <use>-Element über href="#id" darauf verweist. So entstehen SVG-Sprites: Viele Icons stecken in einem einzigen SVG, und jedes Icon lässt sich beliebig oft und in beliebiger Größe einbinden.

Die Schnittstelle bringt keine eigenen Methoden mit. Über das Mixin SVGFitToViewBox stellt sie aber zwei wichtige Eigenschaften bereit:

viewBox (SVGAnimatedRect): das Koordinatensystem des Symbols. Damit skaliert der Inhalt passend auf die Breite und Höhe des <use>-Elements.
preserveAspectRatio (SVGAnimatedPreserveAspectRatio): legt fest, wie das Symbol ausgerichtet und skaliert wird, wenn das Seitenverhältnis nicht passt.

Alles Weitere erbt die Schnittstelle von SVGGraphicsElement, SVGElement, Element und Node. Dazu gehören zum Beispiel id, getAttribute() und dataset. Sie brauchen SVGSymbolElement vor allem, wenn Sie Sprites per JavaScript erzeugen, die Symbole eines Sprites auslesen oder die Werte der viewBox auswerten wollen.

Rückgabewert

Typ

SVGSymbolElement

Beschreibung

Eine Instanz, die Sie über document.createElementNS("http://www.w3.org/2000/svg", "symbol") erzeugen oder aus dem DOM abfragen, zum Beispiel mit querySelector("symbol"). Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Symbol per JavaScript erzeugen und mit <use> einbinden

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

const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('width', '96');
svg.setAttribute('height', '48');

// Symbol als Vorlage anlegen (wird selbst nicht dargestellt)
const symbol = document.createElementNS(SVG_NS, 'symbol');
symbol.id = 'icon-kreis';
symbol.setAttribute('viewBox', '0 0 10 10');

const circle = document.createElementNS(SVG_NS, 'circle');
circle.setAttribute('cx', '5');
circle.setAttribute('cy', '5');
circle.setAttribute('r', '4');
circle.setAttribute('fill', 'currentColor');
symbol.append(circle);
svg.append(symbol);

// Zwei Instanzen in verschiedenen Größen und Positionen
for (const [x, size] of [[0, 24], [40, 48]]) {
  const use = document.createElementNS(SVG_NS, 'use');
  use.setAttribute('href', '#icon-kreis');
  use.setAttribute('x', x);
  use.setAttribute('width', size);
  use.setAttribute('height', size);
  svg.append(use);
}

document.body.append(svg);
console.log(symbol instanceof SVGSymbolElement);

true

viewBox eines Symbols auslesen

// HTML: <svg hidden><symbol id="icon-stern" viewBox="0 0 24 24">…</symbol></svg>
const symbol = document.querySelector('#icon-stern');

const { x, y, width, height } = symbol.viewBox.baseVal;
console.log(`viewBox: ${x} ${y} ${width} ${height}`);
console.log('Seitenverhältnis:', width / height);

// preserveAspectRatio ändern: Inhalt füllt die Fläche, Überstand wird abgeschnitten
symbol.setAttribute('preserveAspectRatio', 'xMidYMid slice');
console.log(symbol.preserveAspectRatio.baseVal.meetOrSlice === SVGPreserveAspectRatio.SVG_MEETORSLICE_SLICE);

viewBox: 0 0 24 24 Seitenverhältnis: 1 true

Alle Icons eines Sprites auflisten (z. B. für eine Icon-Galerie)

const SVG_NS = 'http://www.w3.org/2000/svg';
const symbols = [...document.querySelectorAll('svg symbol[id]')]
  .filter((el) => el instanceof SVGSymbolElement);

const gallery = document.createElement('div');

for (const symbol of symbols) {
  const svg = document.createElementNS(SVG_NS, 'svg');
  svg.setAttribute('width', '32');
  svg.setAttribute('height', '32');
  svg.setAttribute('aria-label', symbol.id);
  svg.setAttribute('role', 'img');

  const use = document.createElementNS(SVG_NS, 'use');
  use.setAttribute('href', `#${symbol.id}`);
  svg.append(use);
  gallery.append(svg);
}

document.body.append(gallery);
console.log(`${symbols.length} Icons gefunden:`, symbols.map((s) => s.id));

3 Icons gefunden: ['icon-kreis', 'icon-stern', 'icon-pfeil']

// Wichtig · Fallstricke

Namensraum beachten: document.createElement('symbol') erzeugt ein wirkungsloses HTMLUnknownElement. SVG-Elemente müssen Sie mit createElementNS('http://www.w3.org/2000/svg', 'symbol') anlegen.
Keine direkte Darstellung: Ein <symbol> wird nie selbst gerendert. Methoden wie getBBox() liefern deshalb am Symbol meist keine brauchbaren Werte. Messen Sie stattdessen das <use>-Element.
href statt xlink:href: Aktuelle Browser verstehen href ohne Namensraum. xlink:href ist veraltet und nur für sehr alte Umgebungen (z. B. Safari < 12) nötig.
Externe Sprites: Ein Verweis wie <use href="sprite.svg#icon"> funktioniert nur innerhalb desselben Ursprungs. Symbole von fremden Ursprüngen werden nicht geladen, auch nicht mit CORS-Headern.
Styling: Inhalte, die per <use> eingebunden sind, liegen in einem geschlossenen Shadow-Tree. CSS-Selektoren von außen greifen dort nicht. Nutzen Sie deshalb vererbte Eigenschaften wie fill: currentColor oder CSS-Variablen.
Vererbung: In SVG 1.1 erbte SVGSymbolElement direkt von SVGElement. In SVG 2 erbt es von SVGGraphicsElement. Die Schnittstelle selbst wird von allen modernen Browsern unterstützt.

Siehe auch

SVGStopElement SVGImageElement SVGMaskElement SVGSVGElement SVGScriptElement