image()

La fonction (en-US) CSS image() définit une image (type <image>) à la façon de la fonction url() mais avec des fonctionnalités supplémentaires comme la définition de la directionnalité, la possibilité d'indiquer une image par défaut si l'image initiale n'est pas prise en charge, l'affichage d'une partie de l'image ou le choix de la couleur à utiliser par défaut si aucune des images indiquées ne peut être affichée.

Note : Attention à ne pas confondre cette notation fonctionnelle CSS avec le constructeur du DOM Image() pour HTMLImageElement.

Syntaxe

Error: could not find syntax for this item

Paramètres

image-tags Facultatif

La directionnalité de l'image, la valeur ltr pourra être utilisée afin d'indiquer que l'image est orientée de gauche à droite ou la valeur rtl pour indiquer une orientation de droite à gauche.

image-src Facultatif

Zéro, une ou plusieurs URL ou chaînes de caractères (<string>) indiquant des sources d'image et qui contiennent éventuellement des identifiants de fragment

color Facultatif

Une couleur par défaut. Cette couleur sera utilisée par défaut si aucune image n'est trouvée ou prise en charge parmi les images fournies via image-src.

Gestion de la directionnalité

Le premier paramètre de la fonction image() est optionnel et indique la directionnalité de l'image. Lorsque ce paramètre est utilisé et que l'image est utilisée au sein d'un élément ayant la directionnalité opposée, l'image sera renversée horizontalement pour les modes d'écriture horizontaux. Si ce paramètre n'est pas utilisé, l'image ne sera pas renversée lorsque du changement de direction de la langue.

Fragments d'image

Une différence fondamentale entre url() et image() est la possibilité d'ajouter un identifiant de fragment d'image. Un identifiant de fragment est donné par : un point de départ défini par ses coordonnées x et y et par une largeur et une hauteur. Cela permet de ne sélectionner qu'une section de l'image source. La section ainsi définie devient une image à part entière aux yeux du moteur de rendu.

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

Avec l'exemple précédent, l'image d'arrière-plan utilisée sera une section de l'image monimage.webp commençant aux coordonnées (0px,20px), ayant une largeur de 40px et une hauteur de 60px.

La syntaxe pour l'identifiant de fragment #xywh=#,#,#,# prend quatre arguments numériques séparés par des virgules. Les deux premiers arguments représentent les coordonnées X et Y du point de départ pour la section, la troisième valeur correspond à la largeur de la portion et la quatrième correspond à la hauteur. Par défaut, ces coordonnées et ces mesures sont exprimées en pixels. La définition de la dimension spatiale de la spécification des médias indique que les pourcentages peuvent également être pris en charge.

xywh=160,120,320,240        /* créera une image sur 320x240 à x=160 et y=120 */
xywh=pixel:160,120,320,240  /* créera une image sur 320x240 à x=160 et y=120 */
xywh=percent:25,25,50,50    /* créera une image sur 50%x50% à x=25% et y=25% */

Les fragments d'image peuvent également être utilisés avec la notation url(). La syntaxe #xywh=#,#,#,# est rétrocompatible, car elle sera ignorée si elle n'est pas comprise et elle ne rendra pas la source invalide si elle est utilisée avec la notation url(). Si le navigateur ne prend pas en charge les notations pour les fragments de média, il ignorera la définition du fragment et affichera l'image intégralement.

Les navigateurs qui prennent en charge image() prennent également en charge la notation pour les fragments. Ainsi si le fragment fourni est invalide dans la source pour image(), l'image résultante sera considérée invalide.

Couleur par défaut

Si les deux derniers arguments sont utilisés et dans le cas où les images fournies sont invalides, la fonction image() génèrera une image à partir de la couleur indiquée. Cette couleur apparaîtra uniquement dans le cas où l'image source n'est pas utilisable. Ainsi, si on a choisi une image sombre sur laquelle afficher du texte clair, autant prévoir une couleur sombre au cas où afin de garantir un contraste acceptable.

Il est possible de ne pas définir d'image source et de ne passer qu'une couleur comme argument.

À la différence de background-color dont la couleur sera placée derrière l'ensemble des images d'arrière-plan, on peut utiliser image() afin de placer des couleurs sur d'autres images (il s'agira le plus souvent de couleurs semi-transparentes dans ce cas).

La taille du rectangle de couleur appliqué peut être définie grâce à la propriété background-size. Ce comportement diffère de background-color qui définit une couleur pour couvrir l'ensemble de l'élément. image(color) et background-color pourront tous les deux être déplacés grâce aux propriétés background-clip et background-origin.

Accessibilité

Les outils d'assistance ne peuvent pas analyser les images d'arrière-plan, car les navigateurs n'extraient pas d'informations du contenu visuel des images. Si l'image contient des informations essentielles à la compréhension du document, il faudra décrire ces informations de façon sémantique dans le document afin, entre autres, que les outils d'assistance puissent transmettre les informations aux utilisateurs.

Cette fonction peut aider à améliorer l'accessibilité en fournissant une couleur par défaut lorsque le chargement d'une image échoue. Bien qu'il faille toujours utiliser background-color comme défaut pour chaque image d'arrière-plan, la fonction CSS image() permet d'ajouter une couleur d'arrière-plan pour toute image dont le chargement échouerait (par exemple un fichier PNG/GIF/WebP avec de la transparence).

Exemples

Utiliser des images prenant en compte la directionnalité

<ul>
  <li dir="ltr">La puce est une flèche pointant à droite et située à gauche</li>
  <li dir="rtl">La puce est la même flèche mais renversée pour pointer à gauche.</li>
</ul>
ul {
  list-style-image: image(ltr 'rightarrow.png');
}

Pour les éléments de la liste allant de gauche à droite (ceux avec dir="ltr" ou qui héritent de cette direction depuis leur ancêtre), l'image pour la puce sera utilisée telle quelle. Les éléments de la liste avec dir="rtl" (que ce soit explicitement défini comme ici ou que cette direction provienne de la direction par défaut du document, par exemple un document en arabe ou en hébreu), l'image sera affichée à droite et sera renversée horizontalement (de la même façon qu'avec transform: scalex(-1)). Le texte sera également affiché de gauche à droite.

Afficher une section de l'image

<div class="box">Vous pouvez survoler cet élément pour voir un autre curseur</div>
.box:hover {
  cursor: image("sprite.png#xywh=32,64,16,16");
}

Lorsqu'on survole la boîte, le curseur changera pour afficher une section d'un sprite mesurant 16 pixels de large et de haut et commençant à x=32 et y=64 sur l'image totale.

Placer une couleur sur une image en arrière-plan

.quarterlogo {
  background-image:
    image(rgba(0, 0, 0, 0.25)),
    url("firefox.png");
  background-size: 25%;
  background-repeat: no-repeat;
}
<div class="quarterlogo">Si pris en charge, un quart de ce div aura un logo assombri</div>

Dans l'exemple précédent, on placera un masque noir semi-transparent sur le logo Firefox utilisé comme image d'arrière-plan. Si on avait utilisé la propriété background-color à la place, la couleur aurait été placée sous le logo et non sur lui. De plus, le conteneur entier aurait eu cette couleur en arrière-plan. Avec image() et background-size (tout en empêchant l'image de se répéter grâce à background-repeat), le voile noir ne couvrira qu'un quart du conteneur.

Spécifications

Specification
CSS Image Values and Replaced Content Module Level 4
# image-notation

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi