CSS-Funktion image()

Syntax

/* Basic usage */
image("image1.jpg");
image(url("image2.jpg"));

/* Bidi-sensitive Images */
image(ltr "image1.jpg");
image(rtl "image1.jpg");

/* Image Fallbacks */
image("image1.jpg", black);

/* Image Fragments */
image("image1.jpg#xywh=40,0,20,20");

/* Solid-color Images */
image(rgb(0 0 255 / 0.5)), url("bg-image.png");

Werte

image-tags Optional

Die Richtung des Bildes: ltr für links nach rechts oder rtl für rechts nach links.

image-src Optional

Null oder mehr <url>- oder <string>-Werte, die die Bildquellen angeben, optional mit Bildfragmentbezeichnern.

color Optional

Eine Farbe, die als einfarbiger Hintergrund verwendet wird, falls keine image-src gefunden wird, unterstützt wird oder angegeben ist.

Berücksichtigung der Schreibrichtung

Der erste, optionale Parameter der image()-Notation gibt die Richtung des Bildes an. Ist er angegeben und wird das Bild auf einem Element mit entgegengesetzter Schreibrichtung verwendet, wird es bei horizontalen Schreibmodi horizontal gespiegelt. Wird die Richtung nicht angegeben, wird das Bild bei einer Änderung der Schreibrichtung nicht gespiegelt.

Bildfragmente

Ein wesentlicher Unterschied zwischen url() und image() besteht darin, dass der Bildquelle ein Medienfragmentbezeichner hinzugefügt werden kann. Dieser legt einen Startpunkt auf der x- und y-Achse sowie eine Breite und Höhe fest, sodass nur ein Ausschnitt des Quellbildes angezeigt wird. Der im Parameter definierte Ausschnitt wird zu einem eigenständigen Bild. Die Syntax sieht so aus:

background-image: image("my-image.webp#xywh=0,20,40,60");

Das Hintergrundbild des Elements ist der Ausschnitt aus myImage.webp, der bei den Koordinaten 0px, 20px beginnt – an seiner linken oberen Ecke – und 40px breit sowie 60px hoch ist.

Die Medienfragmentsyntax #xywh=#,#,#,# verwendet vier durch Kommas getrennte Zahlenwerte. Die ersten beiden geben die X- und Y-Koordinaten des Startpunkts des zu erstellenden Ausschnitts an. Der dritte Wert ist seine Breite, der letzte seine Höhe. Standardmäßig sind diese Werte Pixelangaben. Laut der Definition räumlicher Dimensionen in der Medienfragment-Spezifikation sollen auch Prozentangaben unterstützt werden:

xywh=160,120,320,240        /* results in a 320x240 image at x=160 and y=120 */
xywh=pixel:160,120,320,240  /* results in a 320x240 image at x=160 and y=120 */
xywh=percent:25,25,50,50    /* results in a 50%x50% image at x=25% and y=25% */

Bildfragmente können auch in der url()-Notation verwendet werden. Die Medienfragmentsyntax #xywh=#,#,#,# ist „abwärtskompatibel“: Wird ein Medienfragment nicht verstanden, wird es ignoriert, ohne dass die Quellenangabe bei Verwendung mit url() ungültig wird. Versteht der Browser die Medienfragmentnotation nicht, ignoriert er das Fragment und zeigt das gesamte Bild an.

Browser, die image() verstehen, verstehen auch die Fragmentnotation. Wird das Fragment innerhalb von image() nicht verstanden, gilt das Bild daher als ungültig.

Ersatzfarbe

Wird in image() neben den Bildquellen eine Farbe angegeben, dient sie als Ersatz, wenn die Bilder ungültig sind und nicht angezeigt werden. In diesem Fall rendert die Funktion image() ein einfarbiges Bild, als wäre kein Bild angegeben worden. Stellen Sie sich beispielsweise ein dunkles Bild als Hintergrund für weißen Text vor. Falls das Bild nicht gerendert wird, kann eine dunkle Hintergrundfarbe erforderlich sein, damit der Text lesbar bleibt.

Es ist zulässig, die Bildquellen wegzulassen und nur eine Farbe anzugeben. Dadurch entsteht eine einfarbige Fläche. Anders als bei background-color, das unter beziehungsweise hinter allen Hintergrundbildern liegt, können so Farben – üblicherweise halbtransparent – über andere Bilder gelegt werden.

Die Größe der Farbfläche lässt sich mit der Eigenschaft background-size festlegen. Das unterscheidet sich von background-color, das die Farbe auf das gesamte Element anwendet. Die Platzierung sowohl von image(color) als auch von background-color wird durch die Eigenschaften background-clip und background-origin beeinflusst.

Formale Syntax

<image()> = 
  image( <image-tags>? [ <image-src>? , <color>? ]! )  

<image-tags> = 
  ltr  |
  rtl  

<image-src> = 
  <url>     |
  <string>  

Barrierefreiheit

Browser stellen Hilfstechnologien keine besonderen Informationen über Hintergrundbilder bereit. Das ist vor allem für Screenreader wichtig: Sie kündigen ein Hintergrundbild nicht an und vermitteln ihren Nutzern daher keine darin enthaltenen Informationen. Enthält das Bild Informationen, die für das Verständnis des Gesamtzwecks der Seite entscheidend sind, sollten Sie diese stattdessen semantisch im Dokument beschreiben.

• MDN: WCAG verstehen – Erläuterungen zu Leitlinie 1.1
• Erfolgskriterium 1.1.1 verstehen | W3C: WCAG 2.0 verstehen

Diese Funktion kann die Barrierefreiheit verbessern, indem sie eine Ersatzfarbe bereitstellt, wenn ein Bild nicht geladen werden kann. Zwar kann und sollte dafür bei jedem Hintergrundbild auch eine Hintergrundfarbe angegeben werden, doch mit der CSS-Funktion image() lässt sich eine Ersatzfarbe festlegen, die nur dann erscheint, wenn das Bild nicht geladen wird. Das ist beispielsweise für transparente PNG-, GIF- oder WebP-Bilder nützlich.

Beispiele

Bilder, die auf die Schreibrichtung reagieren

<ul>
  <li dir="ltr">Bullet is a right facing arrow on the left</li>
  <li dir="rtl">Bullet is the same arrow, flipped to point left.</li>
</ul>

ul {
  list-style-image: image(ltr "rightarrow.png");
}

Bei Listenelementen mit Schreibrichtung von links nach rechts wird das Bild unverändert verwendet. Das gilt für Elemente, bei denen dir="ltr" direkt gesetzt ist, sowie für solche, die diese Schreibrichtung von einem übergeordneten Element oder vom Standardwert der Seite übernehmen. Bei Listenelementen, bei denen dir="rtl" auf dem <li> gesetzt ist oder die die Schreibrichtung von rechts nach links von einem übergeordneten Element übernehmen – etwa in arabisch- oder hebräischsprachigen Dokumenten –, erscheint das Aufzählungszeichen rechts und wird horizontal gespiegelt, als wäre transform: scaleX(-1) gesetzt. Der Text wird ebenfalls von links nach rechts angezeigt.

Einen Ausschnitt des Hintergrundbildes anzeigen

<div class="box">Hover over me. What cursor do you see?</div>

.box:hover {
  cursor: image("sprite.png#xywh=32,64,16,16"), auto;
}

Wenn die nutzende Person den Mauszeiger über das Feld bewegt, ändert sich der Cursor und zeigt den 16 × 16 px großen Ausschnitt des Sprite-Bildes, der bei x=32 und y=64 beginnt.

Farbe über ein Hintergrundbild legen

.quarter-logo {
  height: 200px;
  width: 200px;
  border: 1px solid;
}

.quarter-logo {
  background-image: image(rgb(0 0 0 / 25%)), url("firefox.png");
  background-size: 25%;
  background-repeat: no-repeat;
}

<div class="quarter-logo">
  If supported, a quarter of this div has a darkened logo
</div>

Dadurch wird eine halbtransparente schwarze Maske über das Hintergrundbild mit dem Firefox-Logo gelegt. Hätten wir stattdessen die Eigenschaft background-color verwendet, würde die Farbe hinter dem Logo und nicht darüber erscheinen. Außerdem hätte der gesamte Container dieselbe Hintergrundfarbe. Da wir image() zusammen mit der Eigenschaft background-size verwenden und mit background-repeat verhindern, dass sich das Bild wiederholt, bedeckt die Farbfläche nur ein Viertel des Containers.

Spezifikationen

Browser-Kompatibilität

Derzeit unterstützt kein Browser diese Funktion.

Siehe auch

• <image>
• element()
• <url>
• clip-path
• <gradient>
• image-set()
• cross-fade()
• Modul CSS-Bilder