# DfDarkMode – Dark Mode für Shopware 6.7

> Überblick DfDarkMode fügt der Shopware 6.7 Storefront einen vollständigen Dark Mode hinzu. Das Plugin setzt das Attribut data-bs-theme auf dem html-Wurzelelement der Seite: Ihre unter [data-bs-theme="dark"] deklarierten CSS-Variablen werden automatisch…

- Seite: <https://www.datafirefly.com/de/documentation/dfdarkmode/>
- Sprache: de
- Aktualisiert am: 2026-07-22
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfdarkmode/index.md), [en](https://www.datafirefly.com/en/documentation/dfdarkmode/index.md), [es](https://www.datafirefly.com/es/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/de/documentation/llms.txt>

## Überblick

DfDarkMode fügt der Shopware 6.7 Storefront einen vollständigen Dark Mode hinzu. Das Plugin setzt das Attribut `data-bs-theme` auf dem html-Wurzelelement der Seite: Ihre unter `[data-bs-theme="dark"]` deklarierten CSS-Variablen werden automatisch aktiv, ohne jede Änderung an Ihrem Theme.

- **Automatische Erkennung** der Browser-Einstellung `prefers-color-scheme` (Auto-Modus)
- **Header-Umschalter**: ein Button, der zwischen Auto → Hell → Dunkel wechselt
- **Kundeneinstellung**: visueller Auswahlbereich auf der Profilseite des Kundenkontos
- **Doppelte Persistenz**: Cookie für Gäste, Customer Custom Field für angemeldete Konten
- **Anti-FOUC**: das Theme wird vor dem Rendern der Seite angewendet — kein weißes Aufblitzen
- **Login-Synchronisation**: die Kontoeinstellung wird bei der Anmeldung automatisch wiederhergestellt

## Voraussetzungen

- Shopware 6.7.0 oder höher
- Ein Theme, dessen Farben über CSS-Variablen unter `[data-bs-theme="dark"]` definiert sind (Bootstrap-5.3-Konvention)

Das Plugin liefert keine dunkle Farbpalette mit: es steuert ausschließlich das Attribut `data-bs-theme`. Ihr Dark-Mode-CSS muss bereits im Theme vorhanden sein.

## Installation

1. Kopieren Sie den Ordner `DfDarkMode` nach `custom/plugins/` Ihrer Shopware-Installation.
2. Führen Sie folgende Befehle aus:

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

Nach der Theme-Kompilierung erscheint der Umschalter im Header der Storefront und die Karte „Darstellung" wird auf der Profilseite des Kundenkontos angezeigt.

In der Entwicklungsumgebung verwenden Sie `bin/console theme:compile --active-only` oder den Storefront-Watcher für Hot-Recompiling.

## Funktionsweise

### Die drei Modi

- **Auto** (Standard): folgt der Browser- bzw. Betriebssystemeinstellung. Schaltet der Nutzer sein OS auf dunkel, folgt die Storefront in Echtzeit.
- **Hell**: erzwingt den hellen Modus unabhängig vom Browser.
- **Dunkel**: erzwingt den dunklen Modus unabhängig vom Browser.

### Prioritätsreihenfolge der Einstellung

1. **Angemeldeter Kunde**: das Custom Field `df_dark_mode_preference` des Kontos hat Vorrang vor allem anderen.
2. **Gast**: das Cookie `df-dark-mode` (Laufzeit 1 Jahr).
3. **Keine Einstellung**: Auto-Modus.

### Anti-FOUC

Ein Inline-Skript im head-Tag liest das Cookie und setzt `data-bs-theme`, bevor der Browser die Seite zeichnet. Ergebnis: kein helles Aufblitzen des Hintergrunds beim Laden im Dark Mode, selbst bei langsamer Verbindung.

### Login-Synchronisation

Meldet sich ein Kunde an, wird seine gespeicherte Einstellung in das Cookie kopiert. Das Anti-FOUC-Skript verfügt somit ab der nächsten Seite über den richtigen Wert — auf all seinen Geräten.

## Nutzung durch den Kunden

### Header-Button

Der Button zeigt ein Symbol passend zum aktiven Modus: Monitor (Auto), Sonne (Hell) oder Mond (Dunkel). Jeder Klick wechselt zum nächsten Modus. Die Änderung wird sofort mit sanftem Übergang angewendet und im Hintergrund gespeichert.

### Profilseite des Kontos

Unter **Mein Konto → Profil** bietet eine Karte „Darstellung" drei anklickbare Kacheln (Auto, Hell, Dunkel). Die Auswahl wird im Kundenkonto gespeichert und eine Bestätigungsmeldung angezeigt. Tastaturnavigation (Enter / Leertaste) wird unterstützt.

## Anpassung

### Header-Button verschieben

Standardmäßig wird der Umschalter in den Block `base_header_actions_wishlist` eingefügt. Um ihn anderswo zu platzieren, überschreiben Sie das Basis-Template in Ihrem Theme und binden die Komponente im gewünschten Block ein:

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

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

### Auf Theme-Wechsel in JavaScript reagieren

Das Plugin löst bei jedem Wechsel das Event `df-dark-mode-changed` auf `document` aus:

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

Nützlich, um eine Karte, ein Diagramm oder eine Drittkomponente neu zu laden, die keine CSS-Variablen liest.

### Texte und Übersetzungen

Alle Beschriftungen sind Shopware-Snippets (Präfix `df-dark-mode.`), editierbar in der Administration unter **Einstellungen → Textbausteine**. Das Plugin liefert Französisch, Englisch und Deutsch mit.

## Technische Referenz

### Custom Field

Bei der Installation erstellt das Plugin ein Custom-Field-Set `df_dark_mode` mit dem Feld `df_dark_mode_preference` (Select: auto / light / dark), das an die Customer-Entität gebunden ist. Es ist in der Administration auf der Kundendetailseite sichtbar und editierbar.

### AJAX-Route

`POST /df-dark-mode/save` mit dem Parameter `mode` (auto / light / dark). Setzt das Cookie und aktualisiert bei angemeldetem Kunden dessen Custom Field. JSON-Antwort.

### Cookie

Name: `df-dark-mode` · Werte: auto / light / dark · Laufzeit: 365 Tage · SameSite=Lax. Rein funktionales Cookie: es enthält keine personenbezogenen Daten und keine Tracking-Kennung.

## Deinstallation

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

Bei der Deinstallation werden das Custom-Field-Set und die Kundeneinstellungen entfernt, sofern die Option „Benutzerdaten behalten" nicht aktiviert ist.

## Fehlerbehebung

### Der Button erscheint nicht im Header

Stellen Sie sicher, dass das Theme neu kompiliert wurde (`bin/console theme:compile`) und leeren Sie den Cache (`bin/console cache:clear`). Falls Ihr Theme den Block `base_header_actions_wishlist` stark überschreibt, verschieben Sie das Komponenten-Include in einen anderen Block (siehe Anpassung).

### Dark Mode wird aktiviert, aber die Farben ändern sich nicht

Das Plugin setzt `data-bs-theme="dark"` korrekt (im Browser-Inspektor überprüfbar), aber Ihr CSS definiert keine Variablen unter diesem Selektor. Fügen Sie Ihre dunklen Variablen im Block `[data-bs-theme="dark"]` Ihres Themes hinzu.

### Weißes Aufblitzen beim Laden

Stellen Sie sicher, dass kein anderes Plugin den Block `base_head` überschreibt, ohne `{{ parent() }}` aufzurufen — das würde das Anti-FOUC-Skript entfernen.

### Die Einstellung bleibt nicht geräteübergreifend erhalten

Nur angemeldete Kunden profitieren von der geräteübergreifenden Synchronisation über ihr Konto. Bei Gästen ist die Einstellung lokal im Browser gespeichert (Cookie).

## Changelog

### 1.0.0

- Erstveröffentlichung: Browser-Erkennung, Header-Umschalter, Kundenkonto-Einstellung, Anti-FOUC, Login-Synchronisation, FR/EN/DE-Snippets.