SVGPatternElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGPatternElement extends SVGElement

Beschreibung

SVGPatternElement ist die DOM-Schnittstelle des SVG-Elements <pattern>. Ein Muster beschreibt eine Grafik, die als Kachel wiederholt wird und über fill="url(#id)" oder stroke="url(#id)" als Füllung bzw. Kontur anderer Formen dient, etwa für Schraffuren, Punktraster oder Texturen.

Die Schnittstelle erbt von SVGElement und bindet außerdem die Mixins SVGFitToViewBox (viewBox, preserveAspectRatio) und SVGURIReference (href) ein. Alle eigenen Eigenschaften sind animierte Werte (SVGAnimatedLength, SVGAnimatedEnumeration, SVGAnimatedTransformList). Den statischen Wert liest und setzt man über .baseVal, den aktuell (ggf. durch SMIL animierten) Wert liest man über .animVal.

Wichtige Eigenschaften:

x, y, width, height (SVGAnimatedLength): Position und Größe der Musterkachel.
patternUnits (SVGAnimatedEnumeration): Bezugssystem für x/y/width/height: userSpaceOnUse (1) oder objectBoundingBox (2, Standard).
patternContentUnits (SVGAnimatedEnumeration): Bezugssystem für den Inhalt des Musters (Standard: userSpaceOnUse).
patternTransform (SVGAnimatedTransformList): zusätzliche Transformation, z. B. Drehung einer Schraffur.
href (SVGAnimatedString): Verweis auf ein anderes <pattern>, von dem Attribute und Inhalt geerbt werden.
viewBox, preserveAspectRatio: Skalierung des Inhalts innerhalb der Kachel.

Muster erzeugt man per Skript mit document.createElementNS("http://www.w3.org/2000/svg", "pattern") und legt sie üblicherweise in ein <defs>-Element.

Parameter

Name	Typ	Default	Beschreibung
$x / y	SVGAnimatedLength	0	Eigenschaft (schreibgeschützt, Werte über `.baseVal.value` änderbar): Versatz der Musterkachel.
$width / height	SVGAnimatedLength	0	Eigenschaft: Größe der Kachel. Bei `0` wird nichts gezeichnet.
$patternUnits	SVGAnimatedEnumeration	objectBoundingBox (2)	Eigenschaft: Einheitensystem für `x`, `y`, `width`, `height`.
$patternContentUnits	SVGAnimatedEnumeration	userSpaceOnUse (1)	Eigenschaft: Einheitensystem für die Kindelemente des Musters; wird ignoriert, wenn `viewBox` gesetzt ist.
$patternTransform	SVGAnimatedTransformList	leere Liste	Eigenschaft: Transformationsliste, die auf das gesamte Muster angewendet wird.
$href	SVGAnimatedString	""	Eigenschaft: Verweis auf ein Vorlagen-Muster (`href` bzw. veraltet `xlink:href`).

Rückgabewert

Typ

SVGPatternElement

Beschreibung

Instanzen erhält man über document.createElementNS() oder durch Abfrage vorhandener <pattern>-Elemente, z. B. mit querySelector().

Beispiele

Schraffur-Muster per Skript erzeugen und anwenden

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('width', '200');
svg.setAttribute('height', '120');

const defs = document.createElementNS(SVG_NS, 'defs');
const pattern = document.createElementNS(SVG_NS, 'pattern');
pattern.id = 'schraffur';
pattern.setAttribute('patternUnits', 'userSpaceOnUse');
pattern.setAttribute('width', '8');
pattern.setAttribute('height', '8');
pattern.setAttribute('patternTransform', 'rotate(45)');

const linie = document.createElementNS(SVG_NS, 'line');
linie.setAttribute('x1', '0');
linie.setAttribute('y1', '0');
linie.setAttribute('x2', '0');
linie.setAttribute('y2', '8');
linie.setAttribute('stroke', 'steelblue');
linie.setAttribute('stroke-width', '3');

pattern.append(linie);
defs.append(pattern);

const rect = document.createElementNS(SVG_NS, 'rect');
rect.setAttribute('width', '200');
rect.setAttribute('height', '120');
rect.setAttribute('fill', 'url(#schraffur)');

svg.append(defs, rect);
document.body.append(svg);

console.log(pattern instanceof SVGPatternElement);

true

Eigenschaften eines vorhandenen Musters auslesen

// <pattern id="punkte" width="0.1" height="0.1"> ... </pattern>
const pattern = document.querySelector('#punkte');

const units = pattern.patternUnits.baseVal;
const name = units === SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE
  ? 'userSpaceOnUse'
  : 'objectBoundingBox';

console.log(name);
console.log(pattern.width.baseVal.value, pattern.height.baseVal.value);

objectBoundingBox 0.1 0.1

Kachelgröße und Drehung dynamisch ändern

const pattern = document.querySelector('#schraffur');
const svg = pattern.ownerSVGElement;

const setzeDichte = (groesse, winkel) => {
  pattern.width.baseVal.value = groesse;
  pattern.height.baseVal.value = groesse;

  const transform = svg.createSVGTransform();
  transform.setRotate(winkel, 0, 0);
  pattern.patternTransform.baseVal.initialize(transform);
};

// z. B. mit einem Schieberegler koppeln
document.querySelector('#dichte').addEventListener('input', (e) => {
  setzeDichte(Number(e.target.value), 45);
});

// Wichtig · Fallstricke

Namensraum: document.createElement('pattern') erzeugt ein wirkungsloses HTMLUnknownElement. Immer createElementNS('http://www.w3.org/2000/svg', 'pattern') verwenden.
Einheiten-Falle: Standardmäßig gilt patternUnits="objectBoundingBox". Dann ist width="10" das Zehnfache der Objektgröße, und die Kachel wird nie wiederholt. Für Pixelangaben userSpaceOnUse setzen.
Animierte Werte: animVal ist schreibgeschützt. Änderungen immer über baseVal oder setAttribute() vornehmen.
Eindeutige IDs: Mehrere Inline-SVGs auf einer Seite teilen sich den ID-Namensraum. Doppelte Muster-IDs führen zu falschen Füllungen.
href: Das veraltete xlink:href funktioniert weiterhin. Modernere Browser werten aber auch das einfache href aus, das Vorrang hat.
Kompatibilität: Die Schnittstelle wird von allen aktuellen Browsern unterstützt. Sehr viele kleine Kacheln können beim Rendern Leistung kosten, besonders bei Animationen.

Siehe auch

SVGFilterElement SVGMarkerElement SVGPathElement SVGMPathElement SVGPolygonElement