CSSImageValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSImageValue extends CSSStyleValue

Beschreibung

CSSImageValue gehört zur CSS Typed Object Model API (Houdini). Die Schnittstelle stellt CSS-Werte vom Typ <image> als Objekt dar, nicht als einfache Zeichenkette. Solche Objekte liefern zum Beispiel element.computedStyleMap().get('background-image') oder element.attributeStyleMap.get(...), wenn die Eigenschaft ein Bild über url() referenziert.

Die Schnittstelle hat keinen öffentlichen Konstruktor und keine eigenen Eigenschaften oder Methoden. Sie erbt nur von CSSStyleValue, vor allem toString(). Damit bekommt man die serialisierte CSS-Schreibweise, z. B. url("https://example.com/bild.png"). Mit instanceof CSSImageValue lässt sich prüfen, ob eine Eigenschaft tatsächlich ein Bild enthält und nicht etwa das Schlüsselwort none (ein CSSKeywordValue).

Besonders nützlich ist CSSImageValue in der CSS Painting API: Registriert man eine benutzerdefinierte Eigenschaft mit syntax: '<image>', bekommt ein Paint Worklet sie als CSSImageValue. Dieses Objekt kann man direkt an ctx.drawImage() übergeben. So lassen sich Bilder in eigenen Hintergrund-Effekten verwenden, ohne sie in JavaScript selbst zu laden.

Rückgabewert

Typ

CSSImageValue

Beschreibung

Instanzen entstehen nur durch den Browser, z. B. als Rückgabewert von StylePropertyMapReadOnly.get() oder CSSStyleValue.parse(). Geerbte Methode: toString() liefert den serialisierten CSS-Wert.

Beispiele

Hintergrundbild eines Elements als CSSImageValue auslesen

// HTML: <div id="hero" style="background-image: url('hero.jpg')"></div>
const hero = document.querySelector('#hero');
const bg = hero.computedStyleMap().get('background-image');

console.log(bg instanceof CSSImageValue);
console.log(bg.toString());

true url("https://example.com/hero.jpg")

Prüfen, ob ein Element überhaupt ein Bild hat

const hasBackgroundImage = (el) => {
  if (!('computedStyleMap' in el)) return null; // Typed OM nicht verfügbar
  const value = el.computedStyleMap().get('background-image');
  // Bei 'none' kommt ein CSSKeywordValue zurück
  return value instanceof CSSImageValue;
};

document.querySelectorAll('.card').forEach((card) => {
  card.classList.toggle('ohne-bild', hasBackgroundImage(card) === false);
});

Bildwert parsen und per attributeStyleMap setzen

const box = document.querySelector('.box');
const img = CSSStyleValue.parse('background-image', 'url("muster.png")');

console.log(img.constructor.name);
box.attributeStyleMap.set('background-image', img);
console.log(box.style.backgroundImage);

CSSImageValue url("muster.png")

CSSImageValue in einem Paint Worklet zeichnen

// main.js
CSS.registerProperty({
  name: '--kachel',
  syntax: '<image>',
  inherits: false,
  initialValue: 'url("leer.png")'
});
CSS.paintWorklet.addModule('kachel-worklet.js');
// CSS: .flaeche { --kachel: url('stern.png'); background: paint(kachel); }

// kachel-worklet.js
registerPaint('kachel', class {
  static get inputProperties() { return ['--kachel']; }
  paint(ctx, size, props) {
    const bild = props.get('--kachel'); // CSSImageValue
    for (let x = 0; x < size.width; x += 32) {
      for (let y = 0; y < size.height; y += 32) {
        ctx.drawImage(bild, x, y, 32, 32);
      }
    }
  }
});

// Wichtig · Fallstricke

Browserunterstützung: Nur Chromium-Browser (ab Chrome/Edge 66) unterstützen das CSS Typed OM vollständig. Safari hat es ab 16.4 teilweise, Firefox gar nicht. Deshalb vorher prüfen, z. B. mit 'CSSImageValue' in window oder 'computedStyleMap' in Element.prototype.
Kein Konstruktor: new CSSImageValue() wirft einen TypeError. Instanzen erzeugt nur der Browser, etwa über CSSStyleValue.parse().
Nicht jedes <image> wird zu einem CSSImageValue: Farbverläufe wie linear-gradient() oder image-set() kommen in Chromium derzeit als einfacher CSSStyleValue zurück, none als CSSKeywordValue. Deshalb immer mit instanceof prüfen.
Keine Metadaten: Maße, intrinsische Größe oder Ladezustand des Bildes sind über die Schnittstelle nicht erreichbar. Dafür braucht man ein HTMLImageElement oder createImageBitmap().
Bei computedStyleMap() sind URLs meist absolut aufgelöst, bei attributeStyleMap bleiben sie so, wie sie angegeben wurden.

Siehe auch

CSSMathValue CSSStyleValue CSSPageRule CSSUnitValue CSSValue