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 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)

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.

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.