# DfDarkMode – Mode sombre pour Shopware 6.7

> Présentation DfDarkMode ajoute un mode sombre complet au storefront Shopware 6.7. Le plugin applique l'attribut data-bs-theme sur la balise racine html de la page : vos variables CSS déclarées sous…

- Page: <https://www.datafirefly.com/documentation/dfdarkmode/>
- Langue: fr
- Mis à jour le: 2026-07-22
- Autres langues: [en](https://www.datafirefly.com/en/documentation/dfdarkmode/index.md), [es](https://www.datafirefly.com/es/documentation/dfdarkmode/index.md), [de](https://www.datafirefly.com/de/documentation/dfdarkmode/index.md), [it](https://www.datafirefly.com/it/documentation/dfdarkmode/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfdarkmode/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdarkmode/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdarkmode/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

## Présentation

DfDarkMode ajoute un mode sombre complet au storefront Shopware 6.7. Le plugin applique l'attribut `data-bs-theme` sur la balise racine html de la page : vos variables CSS déclarées sous `[data-bs-theme="dark"]` s'activent automatiquement, sans aucune modification de votre thème.

- **Détection automatique** du réglage `prefers-color-scheme` du navigateur (mode Auto)
- **Toggle dans le header** : un bouton qui cycle entre Auto → Clair → Sombre
- **Préférence client** : sélecteur visuel dans la page profil du compte client
- **Persistance double** : cookie pour les visiteurs, custom field client pour les comptes connectés
- **Anti-FOUC** : le thème est appliqué avant le rendu de la page, aucun flash blanc
- **Synchronisation au login** : la préférence du compte est restaurée automatiquement à la connexion

## Prérequis

- Shopware 6.7.0 ou supérieur
- Un thème dont les couleurs sont définies via des variables CSS sous `[data-bs-theme="dark"]` (convention Bootstrap 5.3)

Le plugin ne fournit pas de palette sombre : il pilote uniquement l'attribut `data-bs-theme`. Vos CSS dark mode doivent déjà exister dans le thème.

## Installation

1. Copiez le dossier `DfDarkMode` dans `custom/plugins/` de votre installation Shopware.
2. Exécutez les commandes suivantes :

```
bin/console plugin:refresh
bin/console plugin:install --activate DfDarkMode
bin/console theme:compile
```

Après compilation du thème, le bouton de bascule apparaît dans le header du storefront et la carte « Apparence » s'affiche dans la page profil du compte client.

En environnement de développement, utilisez `bin/console theme:compile --active-only` ou le watcher storefront pour recompiler à chaud.

## Fonctionnement

### Les trois modes

- **Auto** (défaut) : suit le réglage du navigateur ou du système d'exploitation. Si l'utilisateur bascule son OS en sombre, le storefront suit en temps réel.
- **Clair** : force le mode clair quel que soit le navigateur.
- **Sombre** : force le mode sombre quel que soit le navigateur.

### Ordre de priorité de la préférence

1. **Client connecté** : le custom field `df_dark_mode_preference` du compte client prime sur tout.
2. **Visiteur** : le cookie `df-dark-mode` (durée de vie 1 an).
3. **Aucune préférence** : mode Auto.

### Anti-FOUC

Un script inline placé dans la balise head lit le cookie et applique `data-bs-theme` avant que le navigateur ne peigne la page. Résultat : aucun flash de fond clair lors du chargement en mode sombre, même sur connexion lente.

### Synchronisation au login

À la connexion d'un client, sa préférence enregistrée est copiée dans le cookie. Le script anti-FOUC dispose donc de la bonne valeur dès la page suivante, sur tous ses appareils.

## Utilisation côté client

### Bouton du header

Le bouton affiche une icône selon le mode actif : moniteur (Auto), soleil (Clair) ou lune (Sombre). Chaque clic passe au mode suivant. Le changement est appliqué instantanément avec une transition douce et sauvegardé en arrière-plan.

### Page profil du compte

Dans **Mon compte → Profil**, une carte « Apparence » propose trois vignettes cliquables (Auto, Clair, Sombre). La sélection est enregistrée dans le compte client et un message de confirmation s'affiche. La navigation clavier (Entrée / Espace) est prise en charge.

## Personnalisation

### Déplacer le bouton du header

Par défaut, le toggle est injecté dans le block `base_header_actions_wishlist`. Pour le placer ailleurs, surchargez le template de base dans votre thème et incluez le composant dans le block de votre choix :

```
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_header_actions_search %}
    {{ parent() }}
    {% sw_include '@Storefront/storefront/component/dark-mode-toggle.html.twig' %}
{% endblock %}
```

### Réagir aux changements de thème en JavaScript

Le plugin émet l'événement `df-dark-mode-changed` sur `document` à chaque changement :

```
document.addEventListener('df-dark-mode-changed', (e) => {
    console.log(e.detail.preference);    // 'auto', 'light' ou 'dark'
    console.log(e.detail.resolvedTheme); // 'light' ou 'dark'
});
```

Utile pour recharger une carte, un graphique ou tout composant tiers qui ne lit pas les variables CSS.

### Textes et traductions

Tous les libellés sont des snippets Shopware (préfixe `df-dark-mode.`) modifiables dans l'administration, rubrique **Paramètres → Snippets**. Le plugin embarque le français, l'anglais et l'allemand.

## Référence technique

### Custom field

Le plugin crée à l'installation un set de custom fields `df_dark_mode` contenant le champ `df_dark_mode_preference` (select : auto / light / dark) rattaché à l'entité customer. Il est visible et modifiable dans l'administration sur la fiche client.

### Route AJAX

`POST /df-dark-mode/save` avec le paramètre `mode` (auto / light / dark). Pose le cookie et, si un client est connecté, met à jour son custom field. Réponse JSON.

### Cookie

Nom : `df-dark-mode` · Valeurs : auto / light / dark · Durée : 365 jours · SameSite=Lax. Cookie strictement fonctionnel : il ne contient aucune donnée personnelle ni identifiant de suivi.

## Désinstallation

```
bin/console plugin:deactivate DfDarkMode
bin/console plugin:uninstall DfDarkMode
```

Lors de la désinstallation, le set de custom fields et les préférences clients sont supprimés, sauf si l'option « conserver les données » est cochée.

## Dépannage

### Le bouton n'apparaît pas dans le header

Vérifiez que le thème a bien été recompilé (`bin/console theme:compile`) et videz le cache (`bin/console cache:clear`). Si votre thème surcharge fortement le block `base_header_actions_wishlist`, déplacez l'include du composant dans un autre block (voir Personnalisation).

### Le mode sombre s'active mais les couleurs ne changent pas

Le plugin pose bien `data-bs-theme="dark"` (vérifiable dans l'inspecteur du navigateur) mais vos CSS ne définissent pas de variables sous ce sélecteur. Ajoutez vos variables sombres dans le bloc `[data-bs-theme="dark"]` de votre thème.

### Flash blanc au chargement

Assurez-vous qu'aucun autre plugin ne surcharge le block `base_head` sans appeler `{{ parent() }}`, ce qui supprimerait le script anti-FOUC.

### La préférence n'est pas conservée entre appareils

Seuls les clients connectés bénéficient de la synchronisation multi-appareils via leur compte. Pour les visiteurs, la préférence est locale au navigateur (cookie).

## Changelog

### 1.0.0

- Version initiale : détection navigateur, toggle header, préférence compte client, anti-FOUC, synchronisation au login, snippets FR/EN/DE.