Signatur
Beschreibung
Das Interface PaintSize gehört zur CSS Painting API (Houdini). Ein Objekt dieses Typs wird der Methode paint(ctx, size, properties, args) einer registrierten Paint-Klasse als zweites Argument übergeben. Es beschreibt die Größe der Fläche, die gezeichnet werden soll, in CSS-Pixeln. Meist ist das die Rahmenbox des Elements (Border-Box), bei background-image dagegen der Hintergrund-Malbereich.
Das Objekt hat genau zwei schreibgeschützte Eigenschaften:
width(number): die Breite der Zeichenfläche in CSS-Pixeln.height(number): die Höhe der Zeichenfläche in CSS-Pixeln.
Mit diesen Werten passt man die Grafik an die Größe des Elements an, etwa für Verläufe, Muster, Rahmen oder Platzhalter. Wird das Element größer oder kleiner, ruft der Browser paint() neu auf und übergibt ein neues PaintSize-Objekt. Deshalb sollte man die Größe nicht zwischenspeichern.
Man kann PaintSize nicht selbst erzeugen. Es gibt keinen öffentlichen Konstruktor, und das Interface steht nur im globalen Bereich eines Paint-Worklets (PaintWorkletGlobalScope) zur Verfügung, nicht im normalen Fenster.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $width Pflicht | number | Schreibgeschützt. Breite der Zeichenfläche in CSS-Pixeln. Kann auch eine Kommazahl sein. | |
| $height Pflicht | number | Schreibgeschützt. Höhe der Zeichenfläche in CSS-Pixeln. Kann auch eine Kommazahl sein. |
Rückgabewert
paint() übergeben. Das Objekt hat die Eigenschaften width und height.Beispiele
Worklet registrieren und PaintSize nutzen
// checkerboard.js – läuft im PaintWorkletGlobalScope
class Checkerboard {
paint(ctx, size) {
const tile = 16;
// size ist ein PaintSize-Objekt
for (let y = 0; y < size.height / tile; y++) {
for (let x = 0; x < size.width / tile; x++) {
ctx.fillStyle = (x + y) % 2 ? '#1e88e5' : '#bbdefb';
ctx.fillRect(x * tile, y * tile, tile, tile);
}
}
}
}
registerPaint('checkerboard', Checkerboard);Worklet im Hauptdokument laden und per CSS verwenden
// main.js
if ('paintWorklet' in CSS) {
await CSS.paintWorklet.addModule('checkerboard.js');
const box = document.querySelector('.box');
box.style.backgroundImage = 'paint(checkerboard)';
} else {
console.log('CSS Painting API wird nicht unterstützt');
}Zentrierter Kreis, der sich an die Elementgröße anpasst
// circle.js
registerPaint('circle', class {
static get inputProperties() { return ['--circle-color']; }
paint(ctx, { width, height }, props) {
const radius = Math.min(width, height) / 2;
ctx.fillStyle = props.get('--circle-color').toString().trim() || 'tomato';
ctx.beginPath();
ctx.arc(width / 2, height / 2, radius, 0, 2 * Math.PI);
ctx.fill();
}
});// Wichtig · Fallstricke
Browser-Unterstützung: Nur Chromium-basierte Browser (Chrome, Edge, Opera, Version 65 und neuer) unterstützen PaintSize und die CSS Painting API. Firefox und Safari unterstützen sie nicht. Prüfe daher vorher mit 'paintWorklet' in CSS, ob die API vorhanden ist, und hinterlege im CSS einen Ersatz, zum Beispiel eine Farbe oder einen Verlauf vor der paint()-Angabe.
Sichere Umgebung: Worklets werden nur über HTTPS oder localhost geladen.
Einheiten: width und height sind in CSS-Pixeln angegeben, nicht in Gerätepixeln. Um die Pixeldichte des Bildschirms kümmert sich der Browser selbst. Die Werte können Kommazahlen sein. Runde sie, wenn du Muster exakt am Pixelraster ausrichten willst.
Kein Zwischenspeichern: Der Browser kann paint() jederzeit erneut aufrufen und dabei eine neue Größe übergeben. Außerdem kann er mehrere Instanzen der Paint-Klasse anlegen. Speichere die Größe deshalb nicht in Eigenschaften der Instanz.