SVGFEConvolveMatrixElement.orderX — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.orderX

Beschreibung

Die Eigenschaft orderX der Schnittstelle SVGFEConvolveMatrixElement spiegelt die horizontale Größe der Faltungsmatrix wider, also die Anzahl der Spalten des Kernels. Sie entspricht dem ersten Zahlenwert des SVG-Attributs order am Element <feConvolveMatrix>. Das Gegenstück für die Zeilenanzahl ist orderY.

Der Rückgabewert ist ein SVGAnimatedInteger-Objekt. Über baseVal liest du den im Markup (bzw. per Skript) gesetzten Wert, über animVal den aktuell wirksamen Wert, falls eine SMIL-Animation (<animate>) das Attribut verändert. Ohne Animation sind beide Werte gleich.

Regeln des order-Attributs:

Fehlt order, gilt der Standardwert 3 – orderX.baseVal ist dann 3.
Wird nur eine Zahl angegeben (z. B. order="5"), gilt sie für beide Richtungen: orderX und orderY sind 5.
Bei zwei Zahlen (order="5 3") ist die erste orderX, die zweite orderY.

Praktisch nützlich ist orderX vor allem, um in Skripten die erwartete Länge von kernelMatrix (orderX × orderY Einträge) zu prüfen oder dynamisch passende Kernel zu erzeugen, etwa für Weichzeichner-, Schärfe- oder Kantenfilter.

Rückgabewert

Typ

SVGAnimatedInteger

Beschreibung

Objekt mit baseVal (Basiswert aus dem order-Attribut, Standard 3) und animVal (aktuell animierter Wert). Beide sind ganze Zahlen.

Beispiele

orderX eines Filters auslesen

// HTML:
// <svg width="0" height="0">
//   <filter id="schaerfen">
//     <feConvolveMatrix id="kernel" order="3 3"
//       kernelMatrix="0 -1 0  -1 5 -1  0 -1 0" />
//   </filter>
// </svg>

const conv = document.getElementById('kernel');
console.log(conv.orderX.baseVal);
console.log(conv.orderX.animVal);
console.log(conv.orderY.baseVal);

3 3 3

Standardwert und Einzelwert von order

const NS = 'http://www.w3.org/2000/svg';
const conv = document.createElementNS(NS, 'feConvolveMatrix');

// Kein order-Attribut: Standardwert 3
console.log(conv.orderX.baseVal);

// Nur ein Wert: gilt für X und Y
conv.setAttribute('order', '5');
console.log(conv.orderX.baseVal, conv.orderY.baseVal);

// Zwei Werte: erst X, dann Y
conv.setAttribute('order', '5 3');
console.log(conv.orderX.baseVal, conv.orderY.baseVal);

3 5 5 5 3

Kernel passend zu orderX/orderY erzeugen und prüfen

// Erzeugt einen gleichmäßigen Weichzeichner-Kernel (Box Blur)
const setBoxBlur = (conv, size) => {
  conv.setAttribute('order', `${size} ${size}`);
  const cols = conv.orderX.baseVal;
  const rows = conv.orderY.baseVal;
  const kernel = Array(cols * rows).fill(1);
  conv.setAttribute('kernelMatrix', kernel.join(' '));
  conv.setAttribute('divisor', String(cols * rows));
};

const isKernelValid = (conv) => {
  const expected = conv.orderX.baseVal * conv.orderY.baseVal;
  return conv.kernelMatrix.baseVal.numberOfItems === expected;
};

const conv = document.querySelector('feConvolveMatrix');
setBoxBlur(conv, 5);
console.log(conv.orderX.baseVal, isKernelValid(conv));

5 true

// Wichtig · Fallstricke

Schreibgeschützt: orderX selbst kann nicht neu zugewiesen werden. Zum Ändern solltest du setAttribute('order', 'X Y') verwenden. Wie sich Schreibzugriffe auf orderX.baseVal auf das Attribut auswirken, ist zwischen den Browsern nicht einheitlich – verlass dich nicht darauf.
Passende Matrixgröße: kernelMatrix muss genau orderX × orderY Werte enthalten. Sonst gilt das Filterprimitiv als fehlerhaft und wird je nach Browser ignoriert oder als Durchreichefilter behandelt – ohne Fehlermeldung in der Konsole.
Gültige Werte: order muss eine ganze Zahl größer als 0 sein. Null, negative Werte oder Kommazahlen führen zu einem Fehler im Filter.
Performance: Große Kernel (z. B. 9×9 und mehr) kosten beim Rendern viel Leistung, besonders bei großen Flächen oder Animationen. Für Weichzeichner ist <feGaussianBlur> meist deutlich schneller.
Kompatibilität: Wird von allen modernen Browsern (Chrome, Edge, Firefox, Safari) unterstützt.

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.orderY SVGFEConvolveMatrixElement.kernelMatrix SVGFEConvolveMatrixElement.divisor SVGAnimatedInteger Element.setAttribute()