DF Dark Mode dla PrestaShop 8 i 9: dokumentacja

DF Dark Mode dodaje do sklepu PrestaShop 8 lub 9 pełny tryb ciemny, bez żadnej modyfikacji motywu. Moduł wykrywa preferencję systemową odwiedzającego, zapamiętuje jego wybór i generuje ciemny motyw po stronie serwera.

Instalacja

1. W panelu administracyjnym otwórz Moduły > Menedżer modułów.
2. Kliknij Wgraj moduł i wskaż plik dfdarkmode-1.1.0.zip.
3. Po zakończeniu instalacji kliknij Konfiguruj.

Moduł działa od razu z ustawieniami domyślnymi: silnik „inteligentny filtr”, tryb „automatyczny” i pływający przycisk w prawym dolnym rogu. Do poprawnego działania nie jest potrzebna żadna konfiguracja.

Wybór silnika renderowania

Moduł oferuje dwa silniki. Wyboru dokonujesz w polu Silnik renderowania w konfiguracji.

Inteligentny filtr (zalecany)

Ten silnik odwraca całą stronę, a następnie odwraca z powrotem każde medium (zdjęcia, wideo, ramki iframe, canvas, tła), tak aby zdjęcia produktów zachowały naturalne kolory. Działa na dowolnym motywie, bez konfiguracji i bez dodatkowego CSS.

Dwa ustawienia pozwalają dostroić wynik:

• Jasność (od 50 do 150 %, domyślnie 100): obniż ją lekko, na przykład do 92, jeżeli ciemny wygląd wydaje Ci się zbyt jasny.
• Kontrast (od 50 do 150 %, domyślnie 100).

Generowana paleta

Ten silnik wylicza pełną ciemną gamę z dwóch wybranych przez Ciebie kolorów: koloru tła i koloru akcentu. Automatycznie wyprowadzanych jest z nich dziewięć zmiennych CSS:

• --df-bg: tło strony
• --df-surface, --df-surface-2, --df-surface-3: trzy poziomy powierzchni (karty, nagłówki, stany najechania)
• --df-border: obramowania
• --df-text, --df-text-muted: tekst główny i tekst wyciszony
• --df-accent, --df-accent-hover: akcent i jego stan najechania

Kolor tekstu przycisków jest dobierany automatycznie (jasny albo ciemny) na podstawie względnej luminancji Twojego akcentu, aby zapewnić czytelny kontrast. Ten silnik daje ostrzejszy efekt niż filtr, ale zależnie od motywu może wymagać kilku poprawek CSS.

Tryb domyślny

Pole Tryb domyślny określa, co widzi odwiedzający, który nigdy jeszcze nie użył przycisku:

• Automatyczny: moduł podąża za preferencją systemu operacyjnego odwiedzającego (ustawienie prefers-color-scheme). Jeżeli odwiedzający przełączy urządzenie na tryb ciemny w trakcie przeglądania, sklep zmienia się na żywo, bez przeładowania.
• Jasny: sklep pozostaje jasny, dopóki odwiedzający sam nie poprosi o tryb ciemny.
• Ciemny: sklep domyślnie wyświetla się na ciemno dla wszystkich.

Gdy tylko odwiedzający kliknie przycisk, jego wybór jest zapamiętywany w przeglądarce i ma pierwszeństwo przed trybem domyślnym przy wszystkich kolejnych wizytach.

Umiejscowienie przycisku

Pole Położenie przycisku oferuje dwa tryby.

Przycisk pływający

Okrągły przycisk nałożony na stronę, w jednym z czterech narożników (góra lub dół, lewo lub prawo). Możesz go ukryć na urządzeniach mobilnych osobnym ustawieniem.

Hook motywu

Przycisk jest renderowany w linii, w układzie Twojego motywu. Wybierz docelowy hook z listy:

• displayNav1, displayNav2: górne paski nagłówka (displayNav2 odpowiada strefie w prawym górnym rogu w większości motywów)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

Wariant liniowy przycisku jest bardziej zwarty i przezroczysty: dziedziczy kolory swojego kontenera i wtapia się w nagłówek lub stopkę.

Hook niestandardowy

Jeżeli Twój motyw wykonuje własny hook, wpisz po prostu jego nazwę w polu Nazwa hooka niestandardowego. Moduł zarejestruje go automatycznie przy zapisie formularza, bez pisania choćby linijki kodu. To pole ma pierwszeństwo przed powyższą listą.

Nazwa musi zaczynać się od litery i zawierać wyłącznie litery, cyfry i podkreślenia. Przykład: displayMojPrzelacznik.

Z poziomu szablonu

Integratorzy mogą wyświetlić przycisk w dowolnym miejscu pliku .tpl motywu, składnią widgetu PrestaShop:

{widget name='dfdarkmode'}

To wywołanie zawsze renderuje przycisk, niezależnie od skonfigurowanego trybu położenia.

Przycisk cykliczny o trzech stanach

Włącz opcję Przycisk 3-stanowy, aby przycisk przełączał się między jasnym, ciemnym i automatycznym zamiast prostego przełączania jasny/ciemny. Gdy tryb automatyczny jest aktywny, na przycisku pojawia się mała plakietka „A”.

Wykluczanie elementów

Pole Wykluczone selektory CSS przyjmuje listę selektorów, po jednym w wierszu lub rozdzielonych przecinkami. Pasujące elementy zachowują swój oryginalny jasny wygląd, co jest wygodne dla logo, banera partnera albo widgetu zewnętrznego.

.moje-logo
#baner-partnera
.widget-opinie

Selektory zawierające nawiasy klamrowe, nawiasy ostrokątne lub średniki są ignorowane przy zapisie.

Możesz też dodać bezpośrednio klasę df-no-invert do elementu swojego motywu: zostanie automatycznie zachowany.

Własny CSS

Pole Własny CSS jest wstrzykiwane wyłącznie wtedy, gdy tryb ciemny jest aktywny. Poprzedź swoje reguły selektorem html.df-dark:

html.df-dark .header-banner {
    background: var(--df-surface);
    color: var(--df-text);
}

Zmienne CSS (--df-surface, --df-text i pozostałe) są dostępne wyłącznie przy silniku „generowana paleta”.

API JavaScript

Moduł udostępnia publiczne API na potrzeby Twoich własnych integracji:

// Tryb ustawiony: "light", "dark" albo "auto"
DFDarkMode.get();

// Tryb faktycznie wyświetlany: "light" albo "dark"
DFDarkMode.effective();

// Wymuszenie trybu (zapamiętane w przeglądarce)
DFDarkMode.set('dark');

// Przełączenie
DFDarkMode.toggle();

Przy każdej zmianie trybu na dokumencie emitowane jest zdarzenie:

document.addEventListener('dfdarkmode:change', function (e) {
    console.log(e.detail.mode);  // "light" | "dark" | "auto"
    console.log(e.detail.dark);  // true | false
});

Ponadto każdy element z atrybutem data-df-darkmode-toggle staje się automatycznie wyzwalaczem, bez dodatkowego kodu.

Jak to działa od strony technicznej

Brak mignięcia przy ładowaniu

Synchroniczny skrypt wstrzykiwany w nagłówek strony odczytuje zapamiętaną preferencję i nakłada klasę df-dark na element główny jeszcze przed pierwszym renderowaniem przeglądarki. Odwiedzający w trybie ciemnym nigdy nie zobaczy więc jasnej wersji, nawet na moment.

Odwracanie mediów z powrotem

Przy silniku filtra filtry CSS składają się, gdy są zagnieżdżone: nie znoszą się nawzajem. Zdjęcie umieszczone w elemencie picture, który już został odwrócony z powrotem, zostałoby więc odwrócone dwukrotnie. Moduł neutralizuje ten przypadek regułą zabezpieczającą, która zeruje filtr każdego medium zagnieżdżonego w przodku już odwróconym z powrotem.

Zapamiętywanie

Wybór odwiedzającego jest przechowywany w localStorage jego przeglądarki, pod kluczem dfdm. Żadne dane osobowe nie są zbierane ani przesyłane na serwer: moduł nie używa ciasteczek ani zapytań sieciowych, więc nie ma żadnych konsekwencji na gruncie RODO.

Rozwiązywanie problemów

Zdjęcia produktów wyświetlają się w negatywie

Sprawdź, czy używasz wersji 1.1.0 lub nowszej, a następnie wyczyść cache PrestaShop (Ustawienia zaawansowane > Wydajność > Wyczyść pamięć podręczną). Jeżeli konkretny element nadal jest odwrócony, dodaj jego selektor w polu wykluczonych selektorów.

Przycisk nie pojawia się na wybranym hooku

Niektóre motywy nie wykonują wszystkich standardowych hooków. Sprawdź w Wygląd > Pozycje, czy moduł jest podpięty do docelowego hooka i czy ten hook jest rzeczywiście wywoływany przez Twój motyw. W ostateczności użyj składni widgetu w wybranym pliku .tpl.

Jakiś element pozostaje nieczytelny w trybie ciemnym

Dodaj regułę w polu własnego CSS, poprzedzoną selektorem html.df-dark. Jeżeli problem dotyczy całego bloku, wykluczenie go przez selektory CSS jest zwykle prostsze.

Deinstalacja

Deinstalacja usuwa całą konfigurację modułu. Preferencje zapisane w przeglądarkach Twoich odwiedzających nie są naruszane, ale po usunięciu modułu przestają mieć jakikolwiek skutek.