CanvasPattern — Schnittstelle · JavaScript-Referenz

Signatur

interface CanvasPattern

Beschreibung

CanvasPattern steht für ein Füll- bzw. Linienmuster, das auf einer Bildquelle basiert. Das kann ein HTMLImageElement, SVGImageElement, HTMLCanvasElement, OffscreenCanvas, HTMLVideoElement, VideoFrame oder ImageBitmap sein. Man kann das Interface nicht direkt mit einem Konstruktor erzeugen. Muster entstehen ausschließlich über CanvasRenderingContext2D.createPattern(image, repetition) (oder das Gegenstück bei OffscreenCanvasRenderingContext2D).

Das Objekt ist undurchsichtig: Man kann weder Pixel noch Quelle auslesen. Man weist es nur fillStyle oder strokeStyle zu. Danach füllt bzw. umrandet der Kontext Formen, Text und Pfade mit dem gekachelten Bild. Mit dem Wiederholungsmodus ("repeat", "repeat-x", "repeat-y", "no-repeat") legt man fest, in welche Richtung das Bild gekachelt wird.

Die einzige Methode ist CanvasPattern.prototype.setTransform(matrix). Sie nimmt eine DOMMatrix (oder ein DOMMatrix2DInit-Objekt) entgegen und verschiebt, skaliert oder dreht das Muster, ohne die Transformation des Kontexts zu ändern. Typische Einsatzfälle sind Texturen in Spielen, Hintergründe mit Schraffuren, Diagramm-Füllungen (z. B. gestreifte Balken) und dynamisch erzeugte Kachelmuster aus einem Hilfs-Canvas.

Parameter

Name	Typ	Default	Beschreibung
$matrix	DOMMatrix \| DOMMatrix2DInit	Einheitsmatrix	Parameter von `setTransform()`: Transformationsmatrix, die auf das Muster angewendet wird. Ohne Angabe wird die Transformation des Musters auf die Einheitsmatrix zurückgesetzt.

Rückgabewert

Typ

void

Beschreibung

setTransform() gibt nichts zurück. Das CanvasPattern-Objekt selbst liefert createPattern(); bei einer ungültigen Quelle kann dort auch null zurückkommen.

Beispiele

Muster aus einem Bild erzeugen und als Füllung nutzen

const canvas = document.querySelector('#bühne');
const ctx = canvas.getContext('2d');

const img = new Image();
img.src = '/img/ziegel.png';

// Muster erst erzeugen, wenn das Bild dekodiert ist
img.decode().then(() => {
  const pattern = ctx.createPattern(img, 'repeat');
  console.log(pattern instanceof CanvasPattern);
  ctx.fillStyle = pattern;
  ctx.fillRect(0, 0, canvas.width, canvas.height);
});

true

Schraffur-Muster aus einem Hilfs-Canvas für Diagrammbalken

const tile = new OffscreenCanvas(10, 10);
const tctx = tile.getContext('2d');
tctx.strokeStyle = '#0066cc';
tctx.lineWidth = 2;
tctx.beginPath();
tctx.moveTo(0, 10);
tctx.lineTo(10, 0);
tctx.stroke();

const ctx = document.querySelector('#chart').getContext('2d');
const stripes = ctx.createPattern(tile, 'repeat');

const werte = [120, 80, 150];
werte.forEach((wert, i) => {
  ctx.fillStyle = stripes;
  ctx.fillRect(20 + i * 60, 200 - wert, 40, wert);
  ctx.strokeRect(20 + i * 60, 200 - wert, 40, wert);
});

Muster mit setTransform() skalieren und drehen

const ctx = document.querySelector('#bühne').getContext('2d');
const img = await createImageBitmap(await (await fetch('/img/kachel.png')).blob());

const pattern = ctx.createPattern(img, 'repeat');

// Muster halb so groß und um 45° gedreht – der Kontext bleibt unverändert
const matrix = new DOMMatrix().scale(0.5).rotate(45);
pattern.setTransform(matrix);

ctx.fillStyle = pattern;
ctx.beginPath();
ctx.arc(150, 150, 120, 0, Math.PI * 2);
ctx.fill();

// Wichtig · Fallstricke

Bild muss geladen sein: Ist ein HTMLImageElement noch nicht vollständig geladen, liefert createPattern() null bzw. ein leeres Muster. Deshalb vorher await img.decode() oder das load-Event abwarten.
CORS/Tainting: Stammt das Bild von einem fremden Ursprung ohne passende CORS-Freigabe (crossOrigin="anonymous" plus Access-Control-Allow-Origin), wird der Canvas nach dem Zeichnen als „tainted“ markiert. getImageData(), toDataURL() und toBlob() werfen dann einen SecurityError.
Momentaufnahme: Bei Canvas- oder Video-Quellen hält das Muster den Inhalt zum Zeitpunkt des Aufrufs fest. Spätere Änderungen an der Quelle wirken sich nicht aus. Für animierte Muster muss man createPattern() erneut aufrufen.
Ist der Wiederholungsmodus ein leerer String oder null, gilt "repeat". Ungültige Werte werfen einen SyntaxError.
Das Muster richtet sich am Koordinatenursprung des Kontexts aus, nicht an der gezeichneten Form. Wer es verschieben will, nimmt setTransform() oder ctx.translate().
Kompatibilität: CanvasPattern selbst wird von allen Browsern unterstützt. setTransform() gibt es erst in neueren Versionen (Chrome 68+, Firefox 33+, Safari 11+). In OffscreenCanvas und Workern sind Muster verfügbar.

Siehe auch

CanvasRenderingContext2D.createPattern() CanvasRenderingContext2D.fillStyle CanvasRenderingContext2D.strokeStyle CanvasGradient DOMMatrix OffscreenCanvas