SVGNumberList.initialize() — Methode · JavaScript-Referenz

Signatur

SVGNumberList.prototype.initialize(newItem)

Beschreibung

initialize() setzt eine SVGNumberList in einem Schritt auf genau einen Eintrag zurück. Zuerst werden alle vorhandenen Einträge entfernt und von der Liste gelöst. Danach wird newItem als einziges Element eingefügt. Anschließend gilt numberOfItems === 1.

Zahlenlisten gibt es in SVG vor allem an diesen Stellen:

rotate-Attribut von <text> und <tspan> (text.rotate.baseVal)
values von <feColorMatrix>
kernelMatrix von <feConvolveMatrix>
tableValues der Transferfunktionen <feFuncR>, <feFuncG>, <feFuncB> und <feFuncA>

Die Methode ist praktisch, wenn ein Attribut von mehreren Werten auf einen einzigen Wert zurückgesetzt werden soll. Danach lassen sich mit appendItem() weitere Werte anhängen. Die Änderung wird sofort in das zugehörige Attribut im DOM zurückgeschrieben.

Das neue Element muss ein echtes SVGNumber-Objekt sein. Man erzeugt es mit SVGSVGElement.createSVGNumber() am Wurzel-<svg>-Element. Veränderbar ist nur die Basisliste (baseVal). Die animierte Liste (animVal) ist schreibgeschützt.

Parameter

Name	Typ	Default	Beschreibung
$newItem Pflicht	SVGNumber		Das `SVGNumber`-Objekt, das nach dem Leeren als einziges Element in der Liste stehen soll. Nach SVG 2 wird unter Umständen eine Kopie eingefügt (siehe Hinweise).

Rückgabewert

Typ

SVGNumber

Beschreibung

Das Element, das tatsächlich in die Liste eingefügt wurde. Nach SVG 2 kann das eine Kopie von newItem sein. Spätere Änderungen sollten deshalb über den Rückgabewert laufen.

Beispiele

Rotation einzelner Buchstaben auf einen Wert zurücksetzen

// <svg id="bild"><text id="titel" x="10" y="40" rotate="10 20 30 40">Hallo</text></svg>
const svg = document.getElementById('bild');
const text = document.getElementById('titel');
const liste = text.rotate.baseVal;

console.log(liste.numberOfItems); // 4

const zahl = svg.createSVGNumber();
zahl.value = 15;

const eingefuegt = liste.initialize(zahl);

console.log(liste.numberOfItems);
console.log(eingefuegt.value);
console.log(text.getAttribute('rotate'));

4 1 15 15

Liste zurücksetzen und danach neu aufbauen

// Hilfsfunktion: ersetzt den Inhalt einer SVGNumberList durch ein Zahlen-Array
const setzeZahlen = (svg, liste, werte) => {
  const neueZahl = (v) => {
    const n = svg.createSVGNumber();
    n.value = v;
    return n;
  };
  const [erster, ...rest] = werte;
  liste.initialize(neueZahl(erster));
  rest.forEach((v) => liste.appendItem(neueZahl(v)));
};

const svg = document.querySelector('svg');
const text = svg.querySelector('text');
setzeZahlen(svg, text.rotate.baseVal, [0, 45, 90]);
console.log(text.getAttribute('rotate'));

0 45 90

Fehlerbehandlung bei schreibgeschützter Liste

const svg = document.querySelector('svg');
const text = svg.querySelector('text');
const zahl = svg.createSVGNumber();
zahl.value = 5;

try {
  // animVal ist schreibgeschützt
  text.rotate.animVal.initialize(zahl);
} catch (err) {
  console.log(err.name);
}

NoModificationAllowedError

// Wichtig · Fallstricke

Schreibschutz: Wird initialize() auf animVal oder einer anderen schreibgeschützten Liste aufgerufen, wirft die Methode eine DOMException vom Typ NoModificationAllowedError.
Falscher Typ: Ein einfacher Zahlwert wie liste.initialize(15) führt zu einem TypeError. Das Objekt muss mit createSVGNumber() erzeugt werden.
Kopie oder Original: In SVG 1.1 wurde das übergebene Objekt aus einer anderen Liste entfernt, falls es dort schon enthalten war. Nach SVG 2 wird bei Bedarf eine Kopie eingefügt. Deshalb immer mit dem Rückgabewert weiterarbeiten.
Gelöste Objekte: Zuvor aus der Liste gelesene SVGNumber-Objekte sind nach dem Aufruf nicht mehr mit der Liste verbunden. Änderungen an ihnen wirken sich nicht mehr auf das Attribut aus.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Einfacher ist oft setAttribute('rotate', '15'). Das Listen-Interface lohnt sich vor allem bei häufigen, gezielten Änderungen.

Siehe auch

SVGNumberList SVGNumberList.clear() SVGNumberList.appendItem() SVGNumberList.replaceItem() SVGNumber SVGSVGElement.createSVGNumber() SVGAnimatedNumberList