Composant invisible de connexion aux données. Recupere des données depuis une API REST (URL brute ou via un adapter specialise) et les distribue aux autres composants via le systeme d'événements. Supporte aussi les données JSON inline.

Modes de fonctionnement

Le composant supporte trois modes :

Types d'adapter

En mode adapter, l'attribut api-type sélectionne le provider :

Attributs

Attributs communs

Attributs mode URL brute

Attributs mode adapter

Relever le plafond de lignes : max-records

En mode adaptateur, le chargement complet s'arrête à un plafond de sécurité : 1 000 lignes sur Opendatasoft, 25 000 sur Tabular (125 pages de 200). max-records le relève explicitement, et vaut pour les deux adaptateurs : Opendatasoft (#233) et Tabular (#1027). Sur Tabular, une carte de toutes les communes (environ 35 000 lignes) demande max-records="40000", soit jusqu'à 200 requêtes de 200 lignes : c'est le prix à peser, en requêtes comme en mémoire. Un limit plus petit reste prioritaire.

<dsfr-data-source id="communes"
  api-type="tabular"
  resource="…"
  max-records="40000">
</dsfr-data-source>

Quand le plafond coupe le jeu, la troncature n'est pas muette : la source la signale (truncated, lisible dans le volet Diagnostic) et un avertissement console cite max-records comme moyen de la lever. C'est vrai aussi sur un group-by délégué, dont l'API ne donne pas le total : une page pleine au plafond avec une page suivante annoncée suffit à la signaler. Les autres adaptateurs (Grist, INSEE Melodi) ignorent l'attribut.

Tout charger en un seul appel : fetch-mode

En mode adaptateur, la source pagine par tranches de 100 lignes. Pour une page « un fetch, N agrégations client », c'est autant d'allers-retours ; et sur un group-by à beaucoup de groupes, le portail ne rend qu'une page de groupes. fetch-mode="export" passe par l'endpoint d'export du portail, qui rend tout d'un coup, avec les mêmes clauses (select, where, group-by, order-by).

<dsfr-data-source id="src"
  api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr"
  dataset-id="mon-jeu"
  fetch-mode="export"
  max-records="20000">
</dsfr-data-source>

Implémenté par les adaptateurs OpenDataSoft et Tabular ; les autres l'ignorent, et une source dont le portail n'expose pas d'endpoint d'export retombe une fois sur le chargement paginé, avec un avertissement console. À ne pas combiner avec server-side, qui pagine page par page et reste sur l'endpoint paginé : la contradiction est signalée dans la console. Sur OpenDataSoft, le total serveur est inconnu en mode export, donc la troncature est détectée en demandant une ligne de plus que le plafond max-records — pensez à relever ce plafond en même temps.

Tabular : l'export Parquet de data.gouv (#1055)

Sur une source api-type="tabular", fetch-mode="export" lit l'export Parquet que data.gouv publie pour chaque ressource, par plages, en ne lisant que les colonnes du select. Mesuré sur le jeu IRVE (223 174 lignes) : le jeu entier en 0,66 s et 17 requêtes, là où la pagination met 10,8 s et 125 requêtes pour 25 000 lignes. Le lecteur (≈ 22 Ko gzip) n'est chargé qu'à ce moment-là : il n'alourdit pas les autres pages.

• Lignes brutes seulement. Avec un where, un group-by, un aggregate ou un order-by délégué — posé sur la source ou transmis par une dsfr-data-query —, la source reste sur la pagination, qui les exécute côté serveur, et le dit une fois en console. Pour « un fetch, N agrégations », posez les calculs sur des dsfr-data-query qui partagent la source : ils restent alors côté client.
• max-records (25 000 par défaut, comme la pagination) borne les lignes lues. Le fichier annonce son nombre de lignes : le total est connu, et une troncature se dit comme en pagination.
• Forme des lignes identique à celle de l'API : entiers en nombres, dates en AAAA-MM-JJ, colonne __id quand aucun select n'est posé. Une ressource sans export retombe sur la pagination, avec un avertissement.
• Pour la première page d'un petit jeu, la pagination reste plus rapide ; l'export l'emporte au-delà de 1 000 à 2 000 lignes.

<dsfr-data-source id="bornes"
  api-type="tabular"
  resource="eb76d20a-8501-400e-b336-d85724de5435"
  select="nom_station, consolidated_latitude, consolidated_longitude"
  fetch-mode="export"
  max-records="250000">
</dsfr-data-source>

Attribut mode inline

Ne rien charger avant le premier filtre

Sans précaution, une source interroge son API dès le montage et rapatrie le jeu entier — une requête coûteuse dont personne ne regarde le résultat sur une page d'exploration, où l'utilisateur va de toute façon commencer par choisir une commune, une année, un thème. require-where retarde le premier appel jusqu'à ce filtre.

<dsfr-data-source id="src" api-type="opendatasoft" require-where
  base-url="https://data.economie.gouv.fr" dataset-id="equipements">
</dsfr-data-source>

<dsfr-data-facets source="src" fields="commune"></dsfr-data-facets>

<dsfr-data-list source="src"
  idle-message="Choisissez une commune pour afficher ses équipements">
</dsfr-data-list>

Ce qui compte comme filtre : les clauses reçues par commande — facettes, recherche, dsfr-data-context, délégation d'un dsfr-data-query. Le where STATIQUE de la source ne compte pas : il fait partie de la définition du jeu, pas du geste de l'utilisateur — le contraire rendrait l'attribut sans effet sur toute source qui restreint déjà son périmètre. Quand le dernier filtre est retiré, la source repasse en attente : jamais de requête « tout » implicite. Sans effet en mode data inline, qui ne fait aucune requête.

Pendant l'attente, la source publie dsfr-data-idle plutôt que des données vides. Les afficheurs en aval (list, display, kpi, chart, podium, search, a11y) rendent alors leur idle-message — « Choisissez un filtre pour afficher les données » par défaut — et non « aucune donnée », qui annoncerait une requête revenue vide. Un pendant purement client existe sur dsfr-data-query.

Pages à onglets : ne charger que ce qu'on regarde

Une page à onglets déclare ses sources pour tous les panneaux ; cinq sur six sont fermés à l'arrivée, et pourtant toutes les requêtes partent au chargement. Avec lazy, la première requête attend qu'un consommateur de la source entre dans une marge de 200 px autour du viewport. Un panneau fermé est en display:none : il n'a pas de boîte, il n'intersecte jamais, et l'observateur se déclenche à l'ouverture de l'onglet.

<!-- Les sources de l'onglet 2 ne partent qu'à son ouverture -->
<dsfr-data-source id="s-clubs" api-type="opendatasoft" lazy
  base-url="https://data.sports.gouv.fr" dataset-id="clubs">
</dsfr-data-source>

<div class="fr-tabs__panel" id="panneau-2">
  <dsfr-data-chart source="s-clubs" type="bar" label-field="dep" value-field="n"></dsfr-data-chart>
</div>

<!-- Cible explicite, quand la détection automatique ne voit pas le bon élément -->
<dsfr-data-source id="s-carte" api-type="opendatasoft" lazy lazy-target="#panneau-3"
  base-url="https://data.sports.gouv.fr" dataset-id="equipements">
</dsfr-data-source>

Ce qui est observé : les feuilles de la chaîne aval (chart, list, kpi, display, podium, a11y, repeat ; pour une couche de carte, la carte qui la porte), suivies à travers les transformateurs. Un dsfr-data-query est un tuyau déclaré en haut de page : l'observer reviendrait à ne rien différer.

Toutes les dégradations vont du côté « on charge » : sans IntersectionObserver, ou si la page ne déclare aucun consommateur (ou si lazy-target ne désigne rien), la source part immédiatement et le dit en console. Une source qui ne chargerait jamais serait pire que le trafic qu'on cherche à éviter.

Ce que lazy ne promet pas : un IntersectionObserver n'est pas continu. Il échantillonne aux temps de rendu ; un défilement par crans rapides peut traverser un consommateur sans jamais le rapporter comme visible — la source reste alors en attente jusqu'au prochain passage. C'est le comportement du navigateur, pas un bug.

Se cumule avec require-where : les deux portes doivent s'ouvrir, et require-where est évalué en premier — c'est son message d'attente que l'utilisateur doit lire. Pendant l'attente de lazy, la source publie dsfr-data-idle avec la raison lazy, que le volet Diagnostic distingue de l'attente d'un filtre.

Filtres et WHERE dynamique

where="population:gt:5000"
where="population:gt:5000, region:in:IDF|OCC|BRE"
where="email:isnull"

where="population > 5000 AND status = 'active'"

<!-- WHERE statique + overlays dynamiques des facettes et recherche -->
<dsfr-data-source id="src" api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  where="categorie_produit = 'Alimentation'"
  server-side page-size="20">
</dsfr-data-source>

<!-- La recherche ajoute un overlay WHERE via server-search -->
<dsfr-data-search id="search" source="src"
  server-search>
</dsfr-data-search>

<!-- Les facettes ajoutent des overlays WHERE -->
<dsfr-data-facets id="facets" source="src"
  fields="categorie_produit, marque_produit" server-facets>
</dsfr-data-facets>

Mode server-side

Avec server-side, dsfr-data-source charge une seule page a la fois et ecoute les commandes des composants en aval pour naviguer entre les pages. Cela permet d'afficher des datasets de milliers d'enregistrements sans tout charger en memoire.

Le composant reagit a trois types de commandes :

Exemples

<dsfr-data-source
  id="prix-ct"
  url="https://data.economie.gouv.fr/api/explore/v2.1/catalog/datasets/prix-controle-technique/records"
  transform="results"
></dsfr-data-source>

<dsfr-data-source
  id="api-privee"
  url="https://mon-api.gouv.fr/data"
  method="POST"
  headers='{"Authorization": "Bearer TOKEN"}'
  params='{"limit": 100, "filters": {"annee": 2024}}'
  transform="data.items"
  refresh="60"
></dsfr-data-source>

<dsfr-data-source
  id="browse"
  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="browse"
  columns="modeles_ou_references:Produit, categorie_produit:Catégorie, marque_produit:Marque"
  pagination="20">
</dsfr-data-list>

<dsfr-data-source
  id="ghibli-films"
  url="https://ghibliapi.vercel.app/films"
  use-proxy
></dsfr-data-source>

<dsfr-data-source
  id="elus"
  api-type="opendatasoft"
  base-url="https://data.iledefrance.fr"
  dataset-id="elus-regionaux"
  where="sexe = 'F'"
></dsfr-data-source>

<dsfr-data-query id="stats" source="elus"
  group-by="groupe_politique"
  aggregate="nom:count:nb"
  order-by="nb:desc">
</dsfr-data-query>

<dsfr-data-chart source="stats" type="bar"
  label-field="groupe_politique" value-field="nb">
</dsfr-data-chart>

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

<dsfr-data-list source="src-ods"
  columns="modeles_ou_references:Produit, categorie_produit:Catégorie, marque_produit:Marque, date_publication:Date"
  server-sort
  pagination="20">
</dsfr-data-list>

<dsfr-data-source
  id="grist-data"
  api-type="grist"
  base-url="https://grist.numerique.gouv.fr/api/docs/DOC_ID/tables/TABLE_ID/records"
  headers='{"Authorization": "Bearer TOKEN"}'
></dsfr-data-source>

<dsfr-data-chart source="grist-data" type="bar"
  label-field="nom" value-field="valeur">
</dsfr-data-chart>

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

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

<dsfr-data-source
  id="inline"
  data='[{"nom":"Paris","pop":2161000},{"nom":"Lyon","pop":516092},{"nom":"Marseille","pop":870731}]'
></dsfr-data-source>

<dsfr-data-chart source="inline" type="bar"
  label-field="nom" value-field="pop">
</dsfr-data-chart>

<script>
  window.DSFR_DATA_KEYS = {
    tmdb: 'Bearer eyJhbGciOiJIUzI1NiJ9...',
    monapi: 'Token abc123'
  };
</script>

<dsfr-data-source
  id="films"
  url="https://api.themoviedb.org/3/movie/popular"
  api-key-ref="tmdb"
  transform="results"
></dsfr-data-source>

<dsfr-data-source
  id="live"
  api-type="opendatasoft"
  base-url="https://data.opendatasoft.com"
  dataset-id="mon-dataset"
  refresh="30"
></dsfr-data-source>

Événements

Le composant emet des événements personnalises via le systeme data-bridge :

• dsfr-data-loaded : Données chargees avec succes (detail : tableau de records)
• dsfr-data-loading : Chargement en cours
• dsfr-data-error : Erreur de chargement (detail : objet Error)
• cache-fallback : Les données proviennent du cache serveur suite a une erreur API (mode DB uniquement)

Méthodes publiques

Conseils d'utilisation