# DF Dark Mode per PrestaShop 8 e 9 — Documentazione > DF Dark Mode aggiunge una modalità scura completa al suo negozio PrestaShop 8 o 9, senza alcuna modifica al tema. Il modulo rileva la preferenza di sistema del visitatore, memorizza… - Pagina: - Lingua: it - Aggiornato il: 2026-07-12 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dfdarkmode-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/dfdarkmode-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/dfdarkmode-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/dfdarkmode-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfdarkmode-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdarkmode-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdarkmode-prestashop/index.md) - Indice: DF Dark Mode aggiunge una modalità scura completa al suo negozio PrestaShop 8 o 9, senza alcuna modifica al tema. Il modulo rileva la preferenza di sistema del visitatore, memorizza la sua scelta e genera il tema scuro lato server. ## Installazione 1. Nel back office, apra **Moduli > Gestore dei moduli**. 2. Clicchi su **Carica un modulo** e trascini il file `dfdarkmode-1.1.0.zip`. 3. Al termine dell'installazione, clicchi su **Configura**. Il modulo è attivo immediatamente con le impostazioni predefinite: motore a filtro intelligente, modalità automatica e pulsante flottante in basso a destra. Non è necessaria alcuna configurazione per un funzionamento corretto. ## Scegliere il motore di rendering Il modulo propone due motori. La scelta si effettua nel campo **Motore di rendering** della configurazione. ### Filtro intelligente (consigliato) Questo motore inverte l'intera pagina e poi contro-inverte ogni media (immagini, video, iframe, canvas, sfondi) affinché le sue foto prodotto conservino i colori naturali. Funziona su qualsiasi tema, senza configurazione né CSS aggiuntivo. Due regolazioni permettono di affinare il risultato: - **Luminosità** (da 50 a 150 %, predefinito 100) — la abbassi leggermente, a 92 per esempio, se il rendering scuro le sembra troppo luminoso. - **Contrasto** (da 50 a 150 %, predefinito 100). ### Palette generata Questo motore calcola una gamma scura completa a partire da due colori a sua scelta: un **colore di sfondo** e un **colore d'accento**. Da essi vengono derivate automaticamente nove variabili CSS: - `--df-bg` — lo sfondo della pagina - `--df-surface`, `--df-surface-2`, `--df-surface-3` — tre livelli di superficie (schede, intestazioni, hover) - `--df-border` — i bordi - `--df-text`, `--df-text-muted` — il testo principale e il testo attenuato - `--df-accent`, `--df-accent-hover` — l'accento e il suo stato hover Il colore del testo dei pulsanti viene scelto automaticamente (chiaro o scuro) in base alla luminanza relativa del suo accento, per garantire un contrasto leggibile. Questo motore produce un risultato più pulito del filtro, ma può richiedere qualche ritocco CSS a seconda del tema. ## Modalità predefinita Il campo **Modalità predefinita** determina ciò che vede un visitatore che non ha ancora usato il pulsante: - **Automatica** — il modulo segue la preferenza del sistema operativo del visitatore (impostazione `prefers-color-scheme`). Se il visitatore passa il dispositivo alla modalità scura durante la navigazione, il negozio lo segue in tempo reale, senza ricaricare. - **Chiara** — il negozio resta chiaro finché il visitatore non richiede la modalità scura. - **Scura** — il negozio viene mostrato scuro a tutti per impostazione predefinita. Non appena il visitatore clicca sul pulsante, la sua scelta viene memorizzata nel browser e prevale sulla modalità predefinita in tutte le visite successive. ## Posizionare il pulsante Il campo **Posizione del pulsante** propone due modalità. ### Pulsante flottante Un pulsante rotondo sovrapposto alla pagina, in uno dei quattro angoli (alto/basso, sinistra/destra). Può nasconderlo su mobile tramite l'impostazione dedicata. ### Hook di tema Il pulsante viene visualizzato in linea, all'interno del layout del suo tema. Selezioni l'hook di destinazione dall'elenco: - `displayNav1`, `displayNav2` — barre superiori dell'header (displayNav2 corrisponde all'area in alto a destra nella maggior parte dei temi) - `displayTop`, `displayNavFullWidth`, `displayBanner` - `displayFooter`, `displayFooterAfter` La variante in linea del pulsante è più compatta e trasparente: eredita i colori del suo contenitore e si fonde con il suo header o il suo footer. ### Hook personalizzato Se il suo tema esegue un hook proprio, basta digitarne il nome nel campo **Nome dell'hook personalizzato**. Il modulo lo registra automaticamente al salvataggio del modulo, senza scrivere una riga di codice. Questo campo ha la priorità sull'elenco precedente. Il nome deve iniziare con una lettera e contenere solo lettere, cifre e trattini bassi. Esempio: `displayMioSwitcher`. ### Da un template Gli integratori possono visualizzare il pulsante ovunque in un file .tpl del tema con la sintassi widget di PrestaShop: ``` {widget name='dfdarkmode'} ``` Questa chiamata mostra sempre il pulsante, qualunque sia la modalità di posizionamento configurata. ### Pulsante a ciclo di tre stati Attivi l'opzione **Pulsante a 3 stati** affinché il pulsante alterni tra chiara, scura e automatica invece del semplice passaggio chiaro/scuro. Un piccolo badge «A» compare sul pulsante quando la modalità automatica è attiva. ## Escludere elementi Il campo **Selettori CSS esclusi** accetta un elenco di selettori, uno per riga o separati da virgole. Gli elementi corrispondenti conservano il loro rendering chiaro originale, comodo per un logo, un banner partner o un widget di terze parti. ``` .mio-logo #banner-partner .widget-recensioni ``` I selettori contenenti parentesi graffe, parentesi angolari o punti e virgola vengono scartati al salvataggio. Può anche aggiungere direttamente la classe `df-no-invert` a un elemento del suo tema: verrà preservato automaticamente. ## CSS personalizzato Il campo **CSS personalizzato** viene iniettato solo quando la modalità scura è attiva. Anteponga alle sue regole `html.df-dark`: ``` html.df-dark .header-banner { background: var(--df-surface); color: var(--df-text); } ``` Le variabili CSS (`--df-surface`, `--df-text`, ecc.) sono disponibili solo con il motore a palette generata. ## API JavaScript Il modulo espone un'API pubblica per le sue integrazioni: ``` // Modalità configurata: "light", "dark" o "auto" DFDarkMode.get(); // Modalità realmente visualizzata: "light" o "dark" DFDarkMode.effective(); // Forzare una modalità (memorizzata nel browser) DFDarkMode.set('dark'); // Alternare DFDarkMode.toggle(); ``` Un evento viene emesso sul documento a ogni cambio di modalità: ``` document.addEventListener('dfdarkmode:change', function (e) { console.log(e.detail.mode); // "light" | "dark" | "auto" console.log(e.detail.dark); // true | false }); ``` Infine, qualsiasi elemento con l'attributo `data-df-darkmode-toggle` diventa automaticamente un attivatore, senza codice aggiuntivo. ## Funzionamento tecnico ### Nessun lampeggio al caricamento Uno script sincrono, iniettato nell'intestazione della pagina, legge la preferenza memorizzata e applica la classe `df-dark` all'elemento radice prima del primo rendering del browser. Il visitatore in modalità scura non vede quindi mai la versione chiara, nemmeno per un istante. ### Contro-inversione dei media Con il motore a filtro, i filtri CSS si compongono quando sono annidati: non si annullano a vicenda. Un'immagine collocata in un elemento `picture` già contro-invertito verrebbe quindi invertita due volte. Il modulo neutralizza questo caso con una regola di protezione che azzera il filtro di ogni media annidato in un antenato già contro-invertito. ### Memorizzazione La scelta del visitatore è archiviata nel `localStorage` del suo browser, con la chiave `dfdm`. Nessun dato personale viene raccolto o trasmesso a un server: il modulo non usa cookie né chiamate di rete, e non ha quindi alcuna implicazione GDPR. ## Risoluzione dei problemi ### Le foto prodotto appaiono in negativo Verifichi di utilizzare la versione 1.1.0 o superiore, poi svuoti la cache di PrestaShop (**Parametri avanzati > Prestazioni > Svuota la cache**). Se un elemento specifico resta invertito, aggiunga il suo selettore nel campo dei selettori esclusi. ### Il pulsante non compare sull'hook scelto Alcuni temi non eseguono tutti gli hook standard. Verifichi in **Design > Posizioni** che il modulo sia effettivamente agganciato all'hook di destinazione e che tale hook venga realmente richiamato dal suo tema. Come ultima risorsa, usi la sintassi widget nel file .tpl che preferisce. ### Un elemento resta illeggibile in modalità scura Aggiunga una regola nel campo CSS personalizzato, con il prefisso `html.df-dark`. Se il problema riguarda un blocco intero, escluderlo tramite i selettori CSS è spesso più semplice. ## Disinstallazione La disinstallazione elimina l'intera configurazione del modulo. Le preferenze salvate nel browser dei suoi visitatori non vengono modificate, ma diventano prive di effetto una volta rimosso il modulo.