# DfDarkMode: tryb ciemny dla Shopware 6.7

> Wprowadzenie DfDarkMode dodaje kompletny tryb ciemny do storefrontu Shopware 6.7. Plugin ustawia atrybut data-bs-theme na głównym tagu html strony: Twoje zmienne CSS zadeklarowane pod [data-bs-theme="dark"] aktywują się automatycznie, bez żadnych…

- Strona: <https://www.datafirefly.com/pl/documentation/dfdarkmode/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [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), [de](https://www.datafirefly.com/de/documentation/dfdarkmode/index.md), [it](https://www.datafirefly.com/it/documentation/dfdarkmode/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdarkmode/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdarkmode/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Wprowadzenie

DfDarkMode dodaje kompletny tryb ciemny do storefrontu Shopware 6.7. Plugin ustawia atrybut `data-bs-theme` na głównym tagu html strony: Twoje zmienne CSS zadeklarowane pod `[data-bs-theme="dark"]` aktywują się automatycznie, bez żadnych modyfikacji motywu.

- **Automatyczne wykrywanie** ustawienia `prefers-color-scheme` przeglądarki (tryb Auto)
- **Przełącznik w nagłówku**: przycisk cyklicznie przechodzący Auto → Jasny → Ciemny
- **Preferencja klienta**: wizualny selektor na stronie profilu konta klienta
- **Podwójna trwałość**: cookie dla odwiedzających, custom field klienta dla zalogowanych kont
- **Anti-FOUC**: motyw jest stosowany przed renderowaniem strony, żadnego białego błysku
- **Synchronizacja przy logowaniu**: preferencja z konta jest automatycznie przywracana po zalogowaniu

## Wymagania

- Shopware 6.7.0 lub nowszy
- Motyw, którego kolory są zdefiniowane przez zmienne CSS pod `[data-bs-theme="dark"]` (konwencja Bootstrap 5.3)

Plugin nie dostarcza ciemnej palety: steruje wyłącznie atrybutem `data-bs-theme`. Twoje CSS-y trybu ciemnego muszą już istnieć w motywie.

## Instalacja

1. Skopiuj katalog `DfDarkMode` do `custom/plugins/` swojej instalacji Shopware.
2. Wykonaj następujące komendy:

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

Po kompilacji motywu przycisk przełączania pojawia się w nagłówku storefrontu, a karta "Wygląd" wyświetla się na stronie profilu konta klienta.

W środowisku deweloperskim użyj `bin/console theme:compile --active-only` albo watchera storefrontu do rekompilacji na gorąco.

## Działanie

### Trzy tryby

- **Auto** (domyślny): podąża za ustawieniem przeglądarki lub systemu operacyjnego. Jeśli użytkownik przełączy swój system na ciemny, storefront podąża w czasie rzeczywistym.
- **Jasny**: wymusza tryb jasny niezależnie od przeglądarki.
- **Ciemny**: wymusza tryb ciemny niezależnie od przeglądarki.

### Kolejność priorytetów preferencji

1. **Zalogowany klient**: custom field `df_dark_mode_preference` konta klienta ma pierwszeństwo przed wszystkim.
2. **Odwiedzający**: cookie `df-dark-mode` (czas życia 1 rok).
3. **Brak preferencji**: tryb Auto.

### Anti-FOUC

Skrypt inline umieszczony w sekcji head odczytuje cookie i ustawia `data-bs-theme`, zanim przeglądarka namaluje stronę. Rezultat: żadnego błysku jasnego tła przy ładowaniu w trybie ciemnym, nawet na wolnym łączu.

### Synchronizacja przy logowaniu

Przy logowaniu klienta jego zapisana preferencja jest kopiowana do cookie. Skrypt anti-FOUC dysponuje więc właściwą wartością już od następnej strony, na wszystkich jego urządzeniach.

## Użytkowanie po stronie klienta

### Przycisk w nagłówku

Przycisk pokazuje ikonę zależnie od aktywnego trybu: monitor (Auto), słońce (Jasny) lub księżyc (Ciemny). Każde kliknięcie przechodzi do następnego trybu. Zmiana jest stosowana natychmiast z łagodną tranzycją i zapisywana w tle.

### Strona profilu konta

W **Moje konto → Profil** karta "Wygląd" oferuje trzy klikalne kafelki (Auto, Jasny, Ciemny). Wybór jest zapisywany w koncie klienta i wyświetla się komunikat potwierdzenia. Obsługiwana jest nawigacja klawiaturą (Enter / Spacja).

## Personalizacja

### Przeniesienie przycisku w nagłówku

Domyślnie przełącznik jest wstrzykiwany w blok `base_header_actions_wishlist`. Aby umieścić go gdzie indziej, nadpisz bazowy szablon w swoim motywie i dołącz komponent w wybranym bloku:

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

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

### Reagowanie na zmiany motywu w JavaScripcie

Plugin emituje zdarzenie `df-dark-mode-changed` na `document` przy każdej zmianie:

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

Przydatne do przeładowania mapy, wykresu lub dowolnego komponentu zewnętrznego, który nie czyta zmiennych CSS.

### Teksty i tłumaczenia

Wszystkie etykiety są snippetami Shopware (prefiks `df-dark-mode.`) edytowalnymi w administracji, sekcja **Ustawienia → Snippety**. Plugin zawiera francuski, angielski i niemiecki.

## Referencja techniczna

### Custom field

Plugin tworzy przy instalacji zestaw custom fields `df_dark_mode` zawierający pole `df_dark_mode_preference` (select: auto / light / dark) przypięte do encji customer. Jest widoczne i edytowalne w administracji na karcie klienta.

### Trasa AJAX

`POST /df-dark-mode/save` z parametrem `mode` (auto / light / dark). Ustawia cookie, a jeśli klient jest zalogowany, aktualizuje jego custom field. Odpowiedź JSON.

### Cookie

Nazwa: `df-dark-mode` · Wartości: auto / light / dark · Czas: 365 dni · SameSite=Lax. Cookie ściśle funkcjonalne: nie zawiera żadnych danych osobowych ani identyfikatora śledzącego.

## Odinstalowanie

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

Przy odinstalowaniu zestaw custom fields i preferencje klientów są usuwane, chyba że zaznaczono opcję "zachowaj dane".

## Rozwiązywanie problemów

### Przycisk nie pojawia się w nagłówku

Sprawdź, czy motyw został przekompilowany (`bin/console theme:compile`), i wyczyść cache (`bin/console cache:clear`). Jeśli Twój motyw mocno nadpisuje blok `base_header_actions_wishlist`, przenieś include komponentu do innego bloku (zobacz Personalizacja).

### Tryb ciemny się włącza, ale kolory się nie zmieniają

Plugin poprawnie ustawia `data-bs-theme="dark"` (do sprawdzenia w inspektorze przeglądarki), ale Twoje CSS-y nie definiują zmiennych pod tym selektorem. Dodaj swoje ciemne zmienne w bloku `[data-bs-theme="dark"]` motywu.

### Biały błysk przy ładowaniu

Upewnij się, że żaden inny plugin nie nadpisuje bloku `base_head` bez wywołania `{{ parent() }}`, co usunęłoby skrypt anti-FOUC.

### Preferencja nie jest zachowywana między urządzeniami

Tylko zalogowani klienci korzystają z synchronizacji między urządzeniami przez swoje konto. Dla odwiedzających preferencja jest lokalna dla przeglądarki (cookie).

## Changelog

### 1.0.0

- Wersja początkowa: wykrywanie przeglądarki, przełącznik w nagłówku, preferencja konta klienta, anti-FOUC, synchronizacja przy logowaniu, snippety FR/EN/DE.