# Personnaliser le mini-panier WooCommerce avec un fragment et l’Interactivity API

> Le mini-panier classique se met à jour par fragments AJAX. Voici comment le personnaliser sans casser sa réactivité, en s'appuyant sur l'Interactivity API du bloc panier.

- Auteur : Clément Hadrot
- Publié le : 2025-06-24
- Mis à jour le : 2025-06-24
- Catégorie : E-commerce
- URL : https://wpmoderne.dev.wordpress-developpement.fr/ecommerce/personnaliser-mini-panier-woocommerce-fragment-interactivity-api/

## L’essentiel

- Le mini-panier classique et le bloc panier utilisent deux mécanismes distincts
- wc_get_cart_item_data prépare l'affichage sans toucher au calcul
- Un état Interactivity mal isolé casse le rafraîchissement des autres blocs

Une agence cliente vend des accessoires personnalisables et voulait afficher, directement dans le mini-panier, une pastille de couleur correspondant à l'option choisie par le client — sans passer par une extension tierce, et sans casser la mise à jour automatique du panier quand une quantité change. Ce genre de demande, en apparence simple, révèle vite une subtilité : WooCommerce dispose de deux systèmes de mini-panier bien distincts selon que le thème utilise l'ancien système de fragments AJAX ou le nouveau bloc panier basé sur l'Interactivity API.

Ce tutoriel couvre la personnalisation dans les deux contextes, avec un focus particulier sur l'Interactivity API, introduite dans WordPress 6.5 et de plus en plus utilisée par les thèmes de blocs récents pour les blocs panier et mini-panier.

## Comprendre le système de fragments classique

Dans un thème classique, le mini-panier repose sur le filtre `woocommerce_add_to_cart_fragments`. Chaque fois qu'une action modifie le panier (ajout, suppression, changement de quantité), WooCommerce régénère en HTML les zones enregistrées comme fragments et les renvoie via AJAX, sans recharger la page. Ajouter un élément personnalisé consiste à s'accrocher à ce filtre pour injecter un fragment de plus, généralement un sélecteur CSS ciblant une zone du gabarit du mini-panier.

```
add_filter( 'woocommerce_add_to_cart_fragments', function( $fragments ) {
    ob_start();
    ?>
    <span class="pastille-couleur-panier">
        <?php foreach ( WC()->cart->get_cart() as $item ) : ?>
            <?php if ( ! empty( $item['couleur_choisie'] ) ) : ?>
                <span style="background-color: <?php echo esc_attr( $item['couleur_choisie'] ); ?>"></span>
            <?php endif; ?>
        <?php endforeach; ?>
    </span>
    <?php
    $fragments['span.pastille-couleur-panier'] = ob_get_clean();
    return $fragments;
} );
```

La donnée `couleur_choisie` doit elle-même avoir été ajoutée à l'article du panier via `woocommerce_add_cart_item_data` au moment de l'ajout au panier, en amont de cette personnalisation d'affichage.

## Le cas du bloc panier et de l'Interactivity API

Les thèmes de blocs récents, à partir de Twenty Twenty-Four et suivants, proposent un bloc Mini-panier construit sur l'Interactivity API plutôt que sur des fragments AJAX classiques. La différence est fondamentale : l'état du panier vit dans un magasin d'état côté client (`store`), synchronisé avec le serveur via la Store API de WooCommerce, et le rendu se met à jour par liaison de données réactive plutôt que par remplacement de HTML complet.

> L'essentiel à retenir : Le mini-panier classique et le bloc panier utilisent deux mécanismes distincts ; wc_get_cart_item_data prépare l'affichage sans toucher au calcul ; Un état Interactivity mal isolé casse le rafraîchissement des autres blocs

Pour ajouter une information personnalisée dans ce contexte, il faut d'abord l'exposer côté serveur dans la réponse de la Store API, généralement via le filtre `woocommerce_store_api_cart_item_response` ou l'extension de schéma de la Store API prévue à cet effet, puis la consommer côté client dans un module qui étend le magasin d'état existant.

```
add_filter( 'woocommerce_store_api_cart_item_response', function( $item_data, $cart_item ) {
    if ( ! empty( $cart_item['couleur_choisie'] ) ) {
        $item_data['extensions']['agence-couleur'] = array(
            'couleur' => sanitize_hex_color( $cart_item['couleur_choisie'] ),
        );
    }
    return $item_data;
}, 10, 2 );
```

Côté client, un module JavaScript enregistré avec `store()` depuis `@wordpress/interactivity` peut alors lire cette extension dans le contexte du bloc et l'afficher sans recharger l'ensemble du panier — seule la zone concernée se met à jour, ce qui évite le clignotement visuel typique des anciens fragments AJAX sur les paniers contenant beaucoup d'articles.

### Le piège de l'état non isolé

Une erreur fréquente consiste à écrire directement dans l'état global du magasin panier plutôt que dans un contexte local au bloc personnalisé. Cela fonctionne en apparence, jusqu'à ce qu'un autre bloc interactif de la page (un compteur de quantité, un bouton de suppression) lise la même clé d'état et se comporte de façon imprévisible après l'ajout de la personnalisation. L'Interactivity API encourage explicitement l'usage de `getContext()` plutôt que `store()` global pour toute donnée propre à un bloc, précisément pour éviter ce genre de collision.

## Choisir la bonne approche selon le thème

- Thème classique (non basé sur les blocs de site complet) : filtre `woocommerce_add_to_cart_fragments`, approche éprouvée et bien documentée.
- Thème de blocs avec bloc Mini-panier natif : extension de la Store API côté serveur, puis module Interactivity côté client.
- Dans les deux cas : ne jamais modifier le calcul du panier dans le code d'affichage — cette logique doit rester dans les hooks de calcul (`woocommerce_before_calculate_totals`), jamais mélangée au rendu.

> Le bloc Mini-panier récompense la discipline : tout ce qui touche à l'affichage doit rester dans le contexte du bloc, jamais dans l'état global. C'est contraignant au début, mais cela évite des heures de débogage sur des interactions qui se marchent dessus.

## En résumé

Personnaliser le mini-panier n'est plus un geste unique depuis l'arrivée de l'Interactivity API : il faut désormais savoir sur quel système repose le thème avant d'écrire la moindre ligne de code. Les fragments AJAX classiques restent parfaitement valables sur les thèmes qui les utilisent encore, mais l'approche par blocs, plus récente, impose une discipline différente — extension de schéma côté serveur, état isolé côté client — qui, une fois comprise, ouvre la voie à des interfaces panier bien plus réactives.