Composant de tableau de données avec fonctionnalites de recherche, filtrage, tri, pagination et export CSV. Se connecte a un <dsfr-data-source> pour recevoir les données dynamiquement.

Attributs

AttributTypeDescription
sourceStringId de la source (ou du transformateur) dont ce tableau consomme les données.
columnsStringDéfinition des colonnes : "clé:Label, cle2:Label2". Omis : toutes les clés présentes dans les données deviennent colonnes, dans leur ordre d'apparition, libellé = clé — le tableau suit un schéma dynamique (aval d'un dsfr-data-pivot, #255).
searchBooleanAfficher un champ de recherche. Recherche TOLÉRANTE, celle de dsfr-data-search : le terme est cherché comme sous-chaîne dans tous les champs de la ligne (hors champs techniques _…), casse ET accents ignorés — « beziers » trouve « Béziers ». Calculée dans le navigateur, sur les lignes reçues ; ignorée en pagination serveur (une dsfr-data-search en amont cherche alors côté serveur).
filtersStringColonnes filtrables: "ministere,statut"
sortStringTri par défaut: "score:desc"
paginationNumberNombre d'éléments par page (0 = pas de pagination)
exportStringFormats d'export disponibles: "csv", "html" (separables par virgule)
captionStringTitre du tableau, rendu dans caption (masqué visuellement, lu par les lecteurs d'écran — RGAA 5.4, #669). À défaut, dérivé de aria-label.
decimalsNumberNombre de décimales des cellules numériques (#666). Absent : au plus 2 décimales, format fr-FR — sauf pour une valeur non nulle inférieure à 0,01 en valeur absolue, qui garde deux chiffres significatifs (0,00123 → « 0,0012 ») au lieu de s'afficher « 0 » (#1282). Posé, ce nombre de décimales est tenu tel quel : decimals="2" rend « 0,00 ». Les exports CSV/HTML ne sont pas concernés.
url-syncBooleanSynchronise le numéro de page dans l'URL (replaceState)
url-page-paramStringNom du paramètre URL pour la page (défaut: "page")
server-sortBooleanActive le tri serveur. Au lieu de trier localement, envoie une commande { orderBy } au source upstream (dsfr-data-query server-side) qui re-fetche les données triees.
columns-autoBooleanComplète columns avec les clés des données qui n'y figurent pas (ordre d'apparition, libellé = clé) : les premières colonnes sont libellées et figées, les suivantes suivent les données (#640).
idle-messageStringMessage rendu quand l'amont attend un filtre (require-where, #690). Distinct de « aucune donnée » : aucune requête n'a été faite. Vide, le libellé par défaut est utilisé.
count-labelStringNom compté par le compteur rendu au-dessus du tableau, à la place de « résultat » : count-label="commune" affiche « 1 234 communes » (#925, AM-077 — même grammaire que dsfr-data-search, #779). Une forme seule prend un « s » au pluriel ; pour un pluriel irrégulier ou un mot invariable, donner les deux formes séparées par une **barre verticale** : count-label="cheval|chevaux", count-label="prix|prix". La virgule ne sépare PAS les deux formes. Poser l'attribut fait aussi passer le nombre par le formateur fr-FR (séparateur de milliers). Sans l'attribut, le compteur est rendu exactement comme avant. La mention « (filtré) » suit le compteur dans les deux cas.

Les anciens noms francais (colonnes, recherche, filtres, tri, server-tri) restent lus en alias deprecies (#300).

Événements : le composant n'émet pas d'événement custom ; il participe au data-bridge en consommateur (abonnement à la source) et émet des commandes dsfr-data-source-command (page, orderBy) en pagination/tri serveur.

Source en panne

Une liste dont la source échoue rend le message de panne et ne garde aucune ligne ; son export (export) ne produit alors aucun fichier. Un seul cas garde des lignes : en pagination serveur, un changement de page refusé laisse la page précédente affichée, sous la phrase « La page 4 n'a pas pu être chargée. Vous consultez toujours la page 3. » La pagination revient sur la page affichée, et redemander la page refusée relance la source. Voir Quand la source est en panne.

Quand la source porte stale-if-error, la liste garde ses lignes pendant une panne passagère, sous l'étiquette « Non actualisé » et la phrase « Chiffres relevés aujourd'hui à 14 h 32. » Recherche, filtres, tri et pagination locaux répondent ; en pagination ou en tri serveur, les autres pages sont neutralisées. L'export reste possible, daté dans son libellé et dans le nom du fichier. Voir Le dernier relevé, sur demande.

En attente d'un filtre

Sur une page d'exploration, l'amont peut porter require-where (<dsfr-data-source> ou <dsfr-data-query>) et ne rien émettre tant qu'aucun filtre n'est posé — un tableau de 19 000 lignes que personne ne lira ne part pas. Le tableau rend alors le texte de idle-message (« Choisissez un filtre pour afficher les données » par défaut) à la place du message « aucune donnée » : rien n'a été demandé, aucune requête n'est revenue vide. Le mécanisme est décrit sur dsfr-data-source.

Classe CSS pilotée par une colonne

Colorer une cellule selon sa valeur ne se fait pas dans le tableau : la règle est une donnée, elle se calcule en amont. cell-class relie une colonne affichée à une colonne de classes produite par le compute de dsfr-data-normalize.

AttributTypeDescription
cell-classStringClasse CSS d'une cellule pilotée par une colonne calculée (#740) : "colonne:colonne_classe", plusieurs paires séparées par des virgules ; "colonne" seul classe la cellule par sa propre valeur. La valeur de la colonne de classe DEVIENT la classe de la cellule (plusieurs classes séparées par des espaces) : produisez-la avec le compute de dsfr-data-normalize, par exemple compute="alerte = when taux >= 50 then 'seuil-ok' else 'seuil-bas'", puis stylez .seuil-bas dans la page. Seuls les identifiants CSS sont retenus, le reste est ignoré. Quand la colonne de classe n'est pas affichée, sa valeur est ajoutée à la cellule en texte pour les lecteurs d'écran : l'information n'est jamais portée par la seule couleur.
 
<dsfr-data-normalize id="calc" source="src"
  compute="alerte = when taux >= 50 then 'seuil-ok' else 'seuil-bas'">
</dsfr-data-normalize>

<dsfr-data-list source="calc"
  columns="commune:Commune, taux:Taux (%)"
  cell-class="taux:alerte">
</dsfr-data-list>

<style>.seuil-bas { color: var(--text-default-error); }</style>

Plusieurs paires se séparent par des virgules ; cell-class="taux" seul classe la cellule par sa propre valeur. Seuls les identifiants CSS sont retenus. Quand la colonne de classes n'est pas affichée, sa valeur est ajoutée à la cellule en texte pour les lecteurs d'écran : l'information n'est jamais portée par la seule couleur.

Filtrer d'un clic sur une ligne

Un tableau sert souvent de sélecteur : on clique une ligne, et les graphiques de la page se recentrent sur elle. refine-on-click nomme le champ dont la valeur de la ligne cliquée devient un filtre eq. Une colonne de sélection est ajoutée en tête du tableau : un bouton par ligne, atteignable au clavier et dont l'état est annoncé (aria-pressed) — la couleur de la ligne n'est jamais la seule marque.

AttributTypeDescription
refine-on-clickStringChamp dont la valeur de la ligne cliquée devient un filtre eq (#734). Premier clic = filtre, second clic sur la même ligne = retrait, clic sur une autre ligne = remplacement. Une colonne de sélection est ajoutée en tête du tableau : un bouton par ligne, atteignable au clavier, dont l'état est annoncé (aria-pressed) — la couleur de la ligne sélectionnée n'est jamais la seule marque. Avec context="id" (recommandé), le tableau s'enregistre comme filtre du dsfr-data-context : diffusion à toutes ses sources cibles au dialecte de chacune, tag dans dsfr-data-context-tags, URL portée par le contexte. Sans context, la clause part directement à source (whereKey list-select-ID) — sans tag ni URL, et le tableau se filtre lui-même (seule la ligne cliquée reste, jusqu'au second clic).
contextStringIdentifiant du dsfr-data-context auquel s'enregistrer en refine-on-click (#734, ADR-104). Le contexte peut être déclaré après le tableau dans la page. Vide = commande directe à source (chemin dégradé).
labelStringLibellé du tag de contexte en refine-on-click (#734). Vide = le libellé de la colonne filtrée, à défaut le nom du champ.
 
<dsfr-data-context id="ctx" sources="src"></dsfr-data-context>
<dsfr-data-context-tags for="ctx"></dsfr-data-context-tags>

<dsfr-data-list
  source="src"
  columns="departement:Département, total:Total"
  refine-on-click="departement"
  context="ctx"
  label="Département">
</dsfr-data-list>

Premier clic = filtre, second clic sur la même ligne = retrait, clic sur une autre ligne = remplacement. Avec context (recommandé), le tableau s'enregistre comme filtre du dsfr-data-context : diffusion à toutes ses sources cibles au dialecte de chacune, tag supprimable, URL portée par le contexte, et label donne son libellé au tag. Sans context, la clause part directement à source — sans tag ni URL, et le tableau se filtre lui-même, ne gardant que la ligne cliquée jusqu'au second clic.

Variantes

1. Tableau simple

Affiche uniquement les données dans un tableau sans fonctionnalites supplementaires.

<dsfr-data-list
  source="sites"
  columns="nom:Nom du site, ministere:Ministere, score_rgaa:RGAA (%)">
</dsfr-data-list>

3. Tableau + filtres

Ajoute des menus deroulants pour filtrer par colonne spécifique.

<dsfr-data-list
  source="sites"
  columns="nom:Nom du site, ministere:Ministere, statut:Statut, score_rgaa:RGAA (%)"
  filters="ministere,statut">
</dsfr-data-list>

4. Tableau + tri

Definit un tri par défaut et permet de trier en cliquant sur les en-tetes.

<dsfr-data-list
  source="sites"
  columns="nom:Nom du site, ministere:Ministere, score_rgaa:RGAA (%)"
  sort="score_rgaa:desc">
</dsfr-data-list>

5. Tableau + pagination

Divise les données en pages pour une meilleure lisibilite.

<dsfr-data-list
  source="sites"
  columns="nom:Nom du site, ministere:Ministere, score_rgaa:RGAA (%)"
  pagination="5">
</dsfr-data-list>

6. Tableau + export CSV

Ajoute un bouton pour exporter les données au format CSV.

<dsfr-data-list
  source="sites"
  columns="nom:Nom du site, ministere:Ministere, score_rgaa:RGAA (%)"
  export="csv">
</dsfr-data-list>

7. Tableau complet

Combine toutes les fonctionnalites : recherche, filtres, tri, pagination et export.

<dsfr-data-list
  source="sites"
  columns="nom:Nom du site, ministere:Ministere, score_rgaa:RGAA (%), score_dsfr:DSFR (%), statut:Statut, certificat_valide:Certificat"
  search
  filters="ministere,statut"
  sort="score_rgaa:desc"
  pagination="10"
  export="csv">
</dsfr-data-list>

8. Pagination serveur

Quand la source utilise paginate, dsfr-data-list détecté automatiquement la pagination serveur. Chaque changement de page declenche un nouvel appel API. Le nombre total d'enregistrements et de pages vient des metadonnees de l'API.

Boutons de bord. À la première et à la dernière page, « Première page », « Page précédente », « Page suivante » et « Dernière page » restent atteignables au clavier : ils portent aria-disabled="true" (jamais disabled), prennent l'apparence inactive du DSFR et ignorent clic et Entrée. Arrivé sur la dernière page par « Page suivante », le focus reste sur le bouton. Vaut en pagination cliente comme serveur. 

<dsfr-data-source id="rappels"
  api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  server-side
  paginate page-size="20">
</dsfr-data-source>

<dsfr-data-list source="rappels"
  columns="modeles_ou_references:Produit, categorie_produit:Catégorie, marque_produit:Marque"
  search
  sort="date_publication:desc"
  pagination="20">
</dsfr-data-list>

Comportement : en mode pagination serveur, le total affiche (ex: "34 874 résultats") vient de meta.total. La recherche, le tri et les filtres ne s'appliquent qu'aux données de la page courante. Pour filtrer sur tout le dataset, utilisez les paramètres API via params.

Pendant le chargement d'une page, seules les lignes laissent la place à « Chargement de la page 4… » : le compte de résultats et la pagination restent en place, à la même hauteur, et le bouton cliqué garde le focus — un usager au clavier enchaîne les pages sans revenir en haut de la liste. La page demandée est annoncée par la région live de la liste. Les fiches (dsfr-data-display) suivent le même contrat.

Conseils d'utilisation

Performance : Pour les grands ensembles de données, utilisez toujours la pagination pour eviter de surcharger le navigateur. Avec paginate sur dsfr-data-source, la pagination est geree côté serveur et seule la page courante est en memoire.

Accessibilité : Le composant inclut automatiquement les attributs ARIA nécessaires pour les lecteurs d'écran.