Signatur
Beschreibung
PaintSize.width gehört zur CSS Painting API (Teil von CSS Houdini). Ein PaintSize-Objekt wird als zweites Argument an die Methode paint(ctx, size, properties, args) eines registrierten Paint Worklets übergeben. Die Eigenschaft width gibt die Breite der Fläche an, die der Browser gerade zeichnen lässt, etwa den Hintergrund oder den Rahmen eines Elements.
Der Wert ist in CSS-Pixeln angegeben und entspricht der Breite des Bereichs, für den die paint()-Funktion aufgerufen wird. Bei background-image: paint(...) ist das normalerweise die Hintergrundfläche des Elements, also die Größe der background positioning area. Die Auflösung für Displays mit hoher Pixeldichte übernimmt der Browser selbst. Deshalb muss man width nicht mit devicePixelRatio multiplizieren.
Man braucht width (meistens zusammen mit height), um Zeichnungen an die Größe des Elements anzupassen, etwa zentrierte Formen, Muster über die ganze Breite oder Verläufe, die sich an Größenänderungen anpassen. Ändert sich die Größe des Elements, ruft der Browser paint() automatisch mit einem neuen PaintSize-Objekt auf.
Rückgabewert
Beispiele
Kreis in der Mitte des Elements zeichnen
// circle-worklet.js – läuft im PaintWorkletGlobalScope
registerPaint('centered-circle', class {
paint(ctx, size) {
const radius = Math.min(size.width, size.height) / 2;
ctx.fillStyle = 'rebeccapurple';
ctx.beginPath();
ctx.arc(size.width / 2, size.height / 2, radius, 0, 2 * Math.PI);
ctx.fill();
}
});
// main.js – im Hauptdokument
if ('paintWorklet' in CSS) {
CSS.paintWorklet.addModule('circle-worklet.js');
}
/* CSS:
.box { width: 300px; height: 150px; background-image: paint(centered-circle); }
*/Streifenmuster über die volle Breite
// stripes-worklet.js
registerPaint('stripes', class {
static get inputProperties() { return ['--stripe-width']; }
paint(ctx, size, props) {
const stripe = parseFloat(props.get('--stripe-width').toString()) || 20;
// Anzahl der Streifen hängt von der aktuellen Breite ab
const count = Math.ceil(size.width / stripe);
for (let i = 0; i < count; i++) {
ctx.fillStyle = i % 2 === 0 ? '#0af' : '#fff';
ctx.fillRect(i * stripe, 0, stripe, size.height);
}
}
});
/* CSS:
.banner { --stripe-width: 25px; background-image: paint(stripes); }
*/Fortschrittsbalken relativ zur Breite
// progress-worklet.js
registerPaint('progress', class {
static get inputProperties() { return ['--progress']; }
paint(ctx, size, props) {
const value = Math.max(0, Math.min(1, parseFloat(props.get('--progress').toString()) || 0));
ctx.fillStyle = '#ddd';
ctx.fillRect(0, 0, size.width, size.height);
ctx.fillStyle = '#2a2';
ctx.fillRect(0, 0, size.width * value, size.height);
}
});
// main.js: Wert ändern löst ein Neuzeichnen aus
document.querySelector('.bar').style.setProperty('--progress', '0.65');// Wichtig · Fallstricke
- Browser-Unterstützung: Die CSS Painting API gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Vor dem Einsatz mit
'paintWorklet' in CSSprüfen, ob die API vorhanden ist, und in CSS einen Fallback angeben, z. B. eine zusätzlichebackground-Deklaration davor. - Nur im Worklet verfügbar:
PaintSizegibt es nur innerhalb vonpaint()imPaintWorkletGlobalScope. Im Hauptthread lässt sich kein solches Objekt erzeugen oder abrufen. - Einheit: Der Wert ist in CSS-Pixeln angegeben, nicht in Gerätepixeln. Den Kontext nicht selbst mit
devicePixelRatioskalieren, das macht der Browser. - Kein Zustand: Der Browser kann
paint()jederzeit und beliebig oft aufrufen, auch mit verschiedenen Instanzen. Deshalbsize.widthbei jedem Aufruf neu verwenden und nicht zwischenspeichern. - Die Eigenschaft ist schreibgeschützt. Zuweisungen haben keine Wirkung.
- Nur HTTPS (sicherer Kontext):
CSS.paintWorklet.addModule()funktioniert nur über HTTPS oder auflocalhost.