SVGUseElement.width — Eigenschaft · JavaScript-Referenz

Signatur

SVGUseElement.width

Beschreibung

Die Eigenschaft width der Schnittstelle SVGUseElement steht für das Attribut width eines <use>-Elements. Sie gibt ein SVGAnimatedLength-Objekt zurück. Dieses Objekt hat zwei Teile: baseVal ist der statische Wert aus dem Attribut und lässt sich beschreiben. animVal ist der Wert, der gerade tatsächlich gilt, etwa während einer SMIL-Animation, und lässt sich nur lesen.

Die Breite wirkt sich nur dann auf die Darstellung aus, wenn das <use>-Element auf ein <svg> oder ein <symbol> verweist. In diesem Fall gibt der Wert die Breite des Anzeigebereichs (Viewport) der Instanz vor. Wie der Inhalt skaliert wird, bestimmen dann viewBox und preserveAspectRatio des referenzierten Elements. Bei einfachen Formen wie <rect> oder <path> hat width keine Wirkung.

Typische Einsätze sind Icon-Sprites, bei denen ein <symbol> mehrfach in unterschiedlichen Größen eingebunden wird, und Grafiken, deren Größe sich zur Laufzeit ändern soll. Die Eigenschaft selbst ist schreibgeschützt: Man kann ihr kein neues Objekt zuweisen, aber über width.baseVal den Wert ändern.

Rückgabewert

Typ

SVGAnimatedLength

Beschreibung

Ein Objekt mit baseVal (ein SVGLength, beschreibbar) und animVal (ein SVGLength, nur lesbar). Über value, valueInSpecifiedUnits, unitType und valueAsString kommt man an den Wert.

Beispiele

Breite einer Symbol-Instanz auslesen

// <svg><symbol id="stern" viewBox="0 0 24 24">...</symbol>
//   <use id="icon" href="#stern" width="48" height="48"/></svg>
const use = document.querySelector('#icon');
const breite = use.width.baseVal;

console.log(breite.value);          // Wert in Benutzereinheiten
console.log(breite.valueAsString);  // Wert wie im Attribut
console.log(breite.unitType === SVGLength.SVG_LENGTHTYPE_NUMBER);

48 48 true

Icon zur Laufzeit vergrößern

const use = document.querySelector('#icon');

const setzeGroesse = (px) => {
  use.width.baseVal.value = px;   // schreibt das width-Attribut
  use.height.baseVal.value = px;
};

setzeGroesse(96);
console.log(use.getAttribute('width'));

96

Breite in Prozent setzen

const use = document.querySelector('#icon');

// Wert und Einheit gemeinsam setzen
use.width.baseVal.newValueSpecifiedUnits(
  SVGLength.SVG_LENGTHTYPE_PERCENTAGE,
  50
);

console.log(use.width.baseVal.valueAsString);
console.log(use.width.baseVal.value); // umgerechnet in Benutzereinheiten

50% (hängt von der Breite des Viewports ab, z. B. 150)

baseVal und animVal bei SMIL-Animation vergleichen

// <use id="icon" href="#stern" width="48">
//   <animate attributeName="width" from="48" to="96" dur="2s" repeatCount="indefinite"/>
// </use>
const use = document.querySelector('#icon');

setTimeout(() => {
  console.log('Basis:', use.width.baseVal.value);
  console.log('Aktuell:', use.width.animVal.value);
}, 1000);

Basis: 48 Aktuell: 72 (ungefähr, je nach Zeitpunkt)

// Wichtig · Fallstricke

Keine Wirkung bei einfachen Formen: width zählt nur, wenn das <use>-Element auf <svg> oder <symbol> verweist. Bei <rect>, <g> und ähnlichen Elementen bleibt die Änderung ohne sichtbaren Effekt. Größe und Lage steuert man dort über transform.
Die Eigenschaft ist schreibgeschützt: use.width = 100 bewirkt nichts und wirft im Strict Mode einen TypeError. Richtig ist use.width.baseVal.value = 100 oder setAttribute('width', '100').
Kein Attribut gesetzt: In SVG 2 gilt dann auto, was bei <symbol>/<svg> als 100% behandelt wird. baseVal.value meldet in diesem Fall je nach Browser trotzdem 0. Nach SVG 1.1 schaltet der Wert 0 die Darstellung ab.
Einheiten: Bei Prozentwerten oder em ist value in Benutzereinheiten umgerechnet. Wer den Originalwert braucht, nimmt valueInSpecifiedUnits oder valueAsString.
CSS hat Vorrang: In modernen Browsern kann width in SVG 2 auch eine CSS-Eigenschaft sein. Eine CSS-Regel überschreibt dann das Attribut, baseVal zeigt aber weiter den Wert des Attributs.
Browser-Unterstützung: Die Eigenschaft funktioniert in allen aktuellen Browsern (Chrome, Firefox, Safari, Edge).

Siehe auch

SVGUseElement SVGUseElement.height SVGUseElement.x SVGUseElement.y SVGUseElement.href SVGAnimatedLength SVGLength