CanvasRenderingContext2D.createPattern() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.createPattern(image, repetition)

Beschreibung

createPattern() erzeugt aus einer Bildquelle ein CanvasPattern-Objekt. Das Muster weist man fillStyle oder strokeStyle zu. Danach wird die Quelle bei jedem Füllen oder Umranden gekachelt, also z. B. mit fillRect(), fill(), stroke() oder fillText().

Typische Einsatzfälle sind Hintergrundtexturen (Holz, Karos, Rauschen), schraffierte Flächen in Diagrammen und gekachelte Spielwelten. Als Quelle eignet sich besonders ein Offscreen-Canvas: Man zeichnet eine kleine Kachel per Code und erzeugt daraus das Muster, ganz ohne externe Bilddatei.

Das Muster ist am Ursprung des Koordinatensystems ausgerichtet, nicht an der gezeichneten Form. Verschieben, drehen oder skalieren lässt es sich mit ctx.translate() vor dem Zeichnen oder mit pattern.setTransform(matrix) und einer DOMMatrix.

Eine Bildquelle muss vollständig geladen sein. Bei einem HTMLImageElement deshalb immer erst nach dem load-Ereignis oder nach await img.decode() aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$image Pflicht	HTMLImageElement \| SVGImageElement \| HTMLVideoElement \| HTMLCanvasElement \| OffscreenCanvas \| ImageBitmap \| VideoFrame		Die Bildquelle für die Kachel. Bei einem Video wird das aktuelle Einzelbild verwendet.
$repetition Pflicht	string \| null	"repeat" (bei "" oder null)	Legt fest, wie gekachelt wird: `"repeat"` (in beide Richtungen), `"repeat-x"` (nur waagerecht), `"repeat-y"` (nur senkrecht) oder `"no-repeat"` (einmalig). Bei einem leeren String oder `null` gilt `"repeat"`.

Rückgabewert

Typ

CanvasPattern | null

Beschreibung

Ein undurchsichtiges CanvasPattern-Objekt. null kommt zurück, wenn die Quelle noch nicht vollständig geladen ist oder keine Bilddaten hat (z. B. ein Bild ohne src oder ein Video, das noch keine Daten geladen hat).

Beispiele

Bild laden und als Kacheltextur verwenden

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

const img = new Image();
img.src = '/texturen/holz.png';
await img.decode(); // sicherstellen, dass das Bild geladen ist

const muster = ctx.createPattern(img, 'repeat');
ctx.fillStyle = muster;
ctx.fillRect(0, 0, canvas.width, canvas.height);

Karomuster aus einem Offscreen-Canvas erzeugen

const kachel = document.createElement('canvas');
kachel.width = kachel.height = 20;
const k = kachel.getContext('2d');
k.fillStyle = '#eee';
k.fillRect(0, 0, 20, 20);
k.fillStyle = '#ccc';
k.fillRect(0, 0, 10, 10);
k.fillRect(10, 10, 10, 10);

const ctx = document.querySelector('canvas').getContext('2d');
ctx.fillStyle = ctx.createPattern(kachel, 'repeat');
ctx.fillRect(0, 0, 300, 150);

Schraffur für einen Diagrammbalken mit setTransform

const kachel = new OffscreenCanvas(8, 8);
const k = kachel.getContext('2d');
k.strokeStyle = '#1e66f5';
k.lineWidth = 2;
k.beginPath();
k.moveTo(0, 8);
k.lineTo(8, 0);
k.stroke();

const ctx = document.querySelector('canvas').getContext('2d');
const schraffur = ctx.createPattern(kachel, 'repeat');
// Muster doppelt so groß darstellen
schraffur.setTransform(new DOMMatrix().scale(2));
ctx.fillStyle = schraffur;
ctx.fillRect(40, 20, 60, 120);
ctx.strokeRect(40, 20, 60, 120);

Nicht geladene Quelle ergibt null

const ctx = document.createElement('canvas').getContext('2d');
const img = new Image(); // kein src gesetzt
console.log(ctx.createPattern(img, 'repeat'));

null

// Wichtig · Fallstricke

Ladezustand: Wird die Methode aufgerufen, bevor das Bild geladen ist, liefert sie null. Einem Canvas mit Breite oder Höhe 0 wirft sie einen InvalidStateError. Deshalb zuerst mit await img.decode() oder im onload-Handler warten.
Ungültiger repetition-Wert: Löst einen SyntaxError aus (z. B. bei \"repeat-xy\").
CORS: Ein Muster aus einem fremden Bild ohne passende CORS-Header (crossOrigin = 'anonymous' plus Access-Control-Allow-Origin) „verunreinigt“ das Canvas (tainted canvas). Danach werfen getImageData(), toDataURL() und toBlob() einen SecurityError.
Ausrichtung: Das Muster ist an den Canvas-Ursprung gebunden. Soll es mit der Form mitlaufen, translate() nutzen oder CanvasPattern.setTransform().
Video: Das Muster zeigt das Einzelbild zum Zeitpunkt des Aufrufs. Für Animation muss es pro Frame neu erzeugt werden.
Kompatibilität: Wird in allen modernen Browsern unterstützt. OffscreenCanvas als Quelle und CanvasPattern.setTransform() brauchen aktuelle Browser-Versionen.

Siehe auch

CanvasRenderingContext2D CanvasPattern CanvasRenderingContext2D.fillStyle CanvasRenderingContext2D.createLinearGradient() CanvasRenderingContext2D.closePath() CanvasRenderingContext2D.getContextAttributes()