<use>

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Das <use>-Element nimmt Knoten innerhalb eines SVG-Dokuments und dupliziert sie an anderer Stelle. Der Effekt ist derselbe, als ob die Knoten in einem nicht exponierten DOM tief geklont und dann an die Stelle eingefügt würden, an der sich das <use>-Element befindet, ähnlich wie bei geklonten <template>-Elementen.

Verwendungskontext

Kategorien	Grafikelement, Grafikreferenzierende Elemente, Strukturelement
Erlaubter Inhalt	Beliebige Anzahl folgender Elemente, in beliebiger Reihenfolge: Animationselemente Beschreibende Elemente

Attribute

href: Die URL zu einem Element/Fragment, das dupliziert werden muss. Siehe Hinweise zur Verwendung für Details zu häufigen Fallstricken.
Wertetyp: <URL>; Standardwert: keiner; Animierbar: ja
xlink:href Veraltet: Eine <IRI>-Referenz zu einem Element/Fragment, das dupliziert werden muss. Wenn sowohl href als auch xlink:href vorhanden sind, wird der Wert von href verwendet.
Wertetyp: <IRI>; Standardwert: keiner; Animierbar: ja

Warnung: Seit SVG 2 ist das xlink:href Attribut zugunsten von href veraltet. Weitere Informationen finden Sie auf der Seite xlink:href.
x: Die x-Koordinate einer zusätzlichen endgültigen Versatztransformation, die auf das <use>-Element angewendet wird.
Wertetyp: <coordinate>; Standardwert: 0; Animierbar: ja
y: Die y-Koordinate einer zusätzlichen endgültigen Versatztransformation, die auf das <use>-Element angewendet wird.
Wertetyp: <coordinate>; Standardwert: 0; Animierbar: ja
width: Die Breite des <use>-Elements.
Wertetyp: <length>; Standardwert: 0; Animierbar: ja
height: Die Höhe des <use>-Elements.
Wertetyp: <length>; Standardwert: 0; Animierbar: ja

Hinweis: width und height haben keinen Effekt auf <use>-Elemente, es sei denn, das referenzierte Element hat ein viewBox - das heißt, sie haben nur einen Effekt, wenn <use> sich auf ein <svg> oder <symbol>-Element bezieht.

Hinweis: Ab SVG2 sind x, y, width und height Geometrie-Eigenschaften, was bedeutet, dass diese Attribute auch als CSS-Eigenschaften für dieses Element verwendet werden können.

DOM-Schnittstelle

Dieses Element implementiert die SVGUseElement-Schnittstelle.

Beispiel

Das folgende Beispiel zeigt, wie man das <use>-Element verwendet, um einen Kreis mit einer anderen Füllfarbe und einer anderen Strichfarbe zu zeichnen. Im letzten Kreis wird stroke="red" ignoriert, da der Strich bereits auf myCircle gesetzt wurde.

html,
body,
svg {
  height: 100%;
}

html

<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
  <circle id="myCircle" cx="5" cy="5" r="4" stroke="blue" />
  <use href="#myCircle" x="10" fill="blue" />
  <use href="#myCircle" x="20" fill="white" stroke="red" />
</svg>

Hinweise zur Verwendung

Die meisten Attribute auf <use> werden ignoriert, wenn das entsprechende Attribut bereits auf dem vom <use> referenzierten Element definiert ist. (Dies unterscheidet sich davon, wie CSS-Stilattributen solche in der Kaskade 'früher' gesetzten Attribute überschreiben). Nur die Attribute x, y, width, height und href auf dem <use>-Element werden oder können einen Effekt haben, wie später beschrieben wird, wenn das referenzierte Element bereits das entsprechende Attribut definiert hat. Jedoch werden alle anderen Attribute, die nicht auf dem referenzierten Element gesetzt sind, auf das <use>-Element angewendet.

Da die geklonten Knoten nicht exponiert sind, muss beim Einsatz von CSS zum Stylen eines <use>-Elements und seiner geklonten Nachkommen vorsichtig vorgegangen werden. CSS-Eigenschaften werden nicht garantiert vom geklonten DOM geerbt, es sei denn, Sie fordern sie explizit durch CSS-Vererbung an.

Aus Sicherheitsgründen können Browser die Same-Origin-Policy auf <use>-Elemente anwenden und sich weigern, eine Cross-Origin-URL im href-Attribut zu laden. Derzeit gibt es keine festgelegte Methode, um eine Cross-Origin-Richtlinie für <use>-Elemente festzulegen.

Laden von Ressourcen aus externen Dateien über `<use>`

Sie können Knoten aus einer externen SVG-Datei über das <use>-Element laden, indem Sie den Pfad der Datei angeben, gefolgt von einem URL-Fragment, das auf die id des zu ladenden Knotens verweist:

html

<svg>
  <use href="../assets/my-svg.svg#my-fragment"></use>
</svg>

Historisch gesehen war immer ein URL-Fragment erforderlich, selbst wenn Sie das gesamte SVG-Dokument laden wollten. In einem solchen Fall würde die id auf dem Root-Element des SVG enthalten sein:

html

<svg xmlns="http://www.w3.org/2000/svg" id="my-fragment">
  <circle cx="150" cy="100" r="80" fill="green" />
</svg>

Moderne Implementierungen wurden jedoch aktualisiert, sodass Sie, wenn Sie das gesamte externe Dokument laden möchten, es ohne URL-Fragment referenzieren können (und die id auf dem Root-Element des SVG ist nicht mehr erforderlich):

html

<svg>
  <use href="../assets/my-svg.svg"></use>
</svg>

Überprüfen Sie die Browser-Kompatibilität-Tabelle für die Unterstützung durch Browser.

Laden von Ressourcen aus Daten-URIs über `<use>`

Das Laden von Ressourcen mit Daten-URIs im href-Attribut ist aus Sicherheitsgründen veraltet. Dies gilt für <use href="data:..." und auch, wenn href durch Verwendung der Methode set oder setAttribute gesetzt wird.

Auch hier sollten Sie die Browser-Kompatibilität-Tabelle für die Unterstützung durch Browser überprüfen.

Spezifikationen

Specification
Scalable Vector Graphics (SVG) 2 # UseElement