Fonction CSS `counters()`

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

La fonction CSS counters() permet de combiner des marqueurs lors de l'imbrication de compteurs. La fonction retourne une chaîne de caractères qui concatène les valeurs actuelles des compteurs nommés et imbriqués, le cas échéant, avec la chaîne de caractères fournie. Le troisième paramètre, optionnel, permet de définir le style de liste.

La fonction counters() est généralement utilisée au sein d'un pseudo-élément avec la propriété content, mais théoriquement, elle peut être utilisée partout où une valeur <string> est acceptée.

La fonction counters() a deux formes : counters(<name>, <string>) et counters(<name>, <string>, <style>). Le texte généré est la valeur de tous les compteurs avec le <name> donné, disposés du plus externe au plus interne, et séparés par la <string> définie. Les compteurs sont rendus dans le <style> indiqué, par défaut decimal si aucun <style> n'est défini.

Exemple interactif

ol {
  counter-reset: index;
  list-style-type: none;
}

li::before {
  counter-increment: index;
  content: counters(index, ".", decimal) " ";
}

<ol>
  <li>Mars</li>
  <li>
    Saturne
    <ol>
      <li>Mimas</li>
      <li>Enceladus</li>
      <li>
        <ol>
          <li>Voyager</li>
          <li>Cassini</li>
        </ol>
      </li>
      <li>Téthys</li>
    </ol>
  </li>
  <li>
    Uranus
    <ol>
      <li>Titan</li>
    </ol>
  </li>
</ol>

Syntaxe

css

/* Utilisation simple - style decimal par défaut */
counters(counter-name, '.');

/* Changement du style d'affichage */
counters(counter-name, '-', upper-roman)

Un compteur n'est pas visible en tant que tel. La fonction counters() (et la fonction counter()) est ce qui la rend utile en retournant du contenu défini par le·la développeur·euse.

Valeurs

La fonction counters() accepte deux ou trois paramètres. Le premier paramètre est le <counter-name>. Le deuxième paramètre est le séparateur <string>. Le troisième paramètre optionnel est le <counter-style>.

<counter-name>: Un identifiant personnalisé (<custom-ident>) qui identifie les compteurs, et qui est le même nom sensible à la casse utilisé avec les valeurs de propriété counter-reset et counter-increment. Le nom du compteur ne peut pas commencer par deux tirets et ne peut pas être none, unset, initial ou inherit. Alternativement, pour les compteurs en ligne à usage unique, la fonction symbols() peut être utilisée à la place d'un compteur nommé dans les navigateurs qui prennent en charge symbols().
<string>: N'importe quel nombre en chaîne de caractères textuels. Les caractères non latins doivent être encodés en utilisant leurs séquences d'échappement Unicode : par exemple, \000A9 représente le symbole de copyright (©).
<counter-style>: Un nom de style de compteur ou une fonction symbols(). Le nom du style de compteur peut être un style prédéfini tel que numérique, alphabétique ou symbolique, un style prédéfini complexe en écriture asiatique ou éthiopienne, ou un autre style de compteur prédéfini. Si omis, le style de compteur par défaut est decimal.

La valeur de retour est une chaîne de caractères contenant toutes les valeurs de tous les compteurs dans l'ensemble de compteurs CSS de l'élément nommé <counter-name> dans le style de compteur défini par <counter-style> (ou décimal, si omis). La chaîne de caractères de retour est triée de l'extérieur vers l'intérieur, jointe par la chaîne de caractères (<string>) définie.

Note : Pour obtenir des informations sur les compteurs non concaténés, consultez la fonction counter(), qui omet le paramètre <string>.

Syntaxe formelle

<counters()> = 
  counters( <counter-name> , <string> , <counter-style>? )  

<counter-name> = 
  <custom-ident>  

<counter-style> = 
  <counter-style-name>  |
  <symbols()>           

<counter-style-name> = 
  <custom-ident>  

<symbols()> = 
  symbols( <symbols-type>? [ <string> | <image> ]+ )  

<symbols-type> = 
  cyclic      |
  numeric     |
  alphabetic  |
  symbolic    |
  fixed       

<image> = 
  <url>           |
  <image()>       |
  <image-set()>   |
  <cross-fade()>  |
  <element()>     |
  <gradient>      

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

<image-set()> = 
  image-set( <image-set-option># )  

<cross-fade()> = 
  cross-fade( <cf-image># )  

<element()> = 
  element( <id-selector> )  

<image-tags> = 
  ltr  |
  rtl  

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

<image-set-option> = 
  [ <image> | <string> ] [ <resolution> || type( <string> ) ]?  

<cf-image> = 
  [ <image> | <color> ]  &&
  <percentage [0,100]>?  

<id-selector> = 
  <hash-token>

Exemples

Comparer la valeur par défaut du compteur avec les chiffres romains majuscules

Cet exemple inclut deux fonctions counters() : l'une avec <counter-style> défini et l'autre utilisant la valeur par défaut decimal.

HTML

html

<ol>
  <li>
    <ol>
      <li></li>
      <li></li>
      <li></li>
    </ol>
  </li>
  <li></li>
  <li></li>
  <li>
    <ol>
      <li></li>
      <li>
        <ol>
          <li></li>
          <li></li>
          <li></li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

CSS

css

ol {
  counter-reset: listCounter;
}
li {
  counter-increment: listCounter;
}
li::marker {
  content:
    counters(listCounter, ".", upper-roman) ") ";
}
li::before {
  content:
    counters(listCounter, ".") " == "
    counters(listCounter, ".", lower-roman);
}

Résultat

Comparer la valeur du compteur `decimal-leading-zero` avec les lettres minuscules

Cet exemple inclut trois fonctions counters(), chacune avec des valeurs <string> et <counter-style> différentes.

HTML

html

<ol>
  <li>
    <ol>
      <li></li>
      <li></li>
      <li></li>
    </ol>
  </li>
  <li></li>
  <li></li>
  <li>
    <ol>
      <li></li>
      <li>
        <ol>
          <li></li>
          <li></li>
          <li></li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

CSS

css

ol {
  counter-reset: count;
}
li {
  counter-increment: count;
}
li::marker {
  content:
    counters(count, "-", decimal-leading-zero) ") ";
}
li::before {
  content:
    counters(count, "~", upper-alpha) " == "
    counters(count,  "*", lower-alpha);
}