DfDarkMode – Modalità scura per Shopware 6.7

Panoramica

DfDarkMode aggiunge una modalità scura completa allo storefront di Shopware 6.7. Il plugin imposta l’attributo data-bs-theme sul tag radice html della pagina: le variabili CSS dichiarate sotto [data-bs-theme="dark"] si attivano automaticamente, senza alcuna modifica al tema.

• Rilevamento automatico dell’impostazione prefers-color-scheme del browser (modalità Auto)
• Pulsante nell’header: un pulsante che alterna tra Auto → Chiaro → Scuro
• Preferenza cliente: selettore visivo nella pagina profilo dell’account
• Doppia persistenza: cookie per i visitatori, custom field cliente per gli account connessi
• Anti-FOUC: il tema viene applicato prima del rendering della pagina, nessun lampo bianco
• Sincronizzazione al login: la preferenza dell’account viene ripristinata automaticamente all’accesso

Requisiti

• Shopware 6.7.0 o superiore
• Un tema i cui colori sono definiti tramite variabili CSS sotto [data-bs-theme="dark"] (convenzione Bootstrap 5.3)

Installazione

1. Copia la cartella DfDarkMode in custom/plugins/ della tua installazione Shopware.
2. Esegui i seguenti comandi:

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

Dopo la compilazione del tema, il pulsante di commutazione appare nell’header dello storefront e la scheda «Aspetto» viene mostrata nella pagina profilo dell’account cliente.

Funzionamento

Le tre modalità

• Auto (predefinita): segue l’impostazione del browser o del sistema operativo. Se l’utente passa il suo SO in modalità scura, lo storefront lo segue in tempo reale.
• Chiaro: forza la modalità chiara indipendentemente dal browser.
• Scuro: forza la modalità scura indipendentemente dal browser.

Ordine di priorità della preferenza

1. Cliente connesso: il custom field df_dark_mode_preference dell’account prevale su tutto.
2. Visitatore: il cookie df-dark-mode (durata 1 anno).
3. Nessuna preferenza: modalità Auto.

Anti-FOUC

Uno script inline posizionato nel tag head legge il cookie e applica data-bs-theme prima che il browser disegni la pagina. Risultato: nessun lampo di sfondo chiaro al caricamento in modalità scura, anche con connessione lenta.

Sincronizzazione al login

Quando un cliente accede, la sua preferenza salvata viene copiata nel cookie. Lo script anti-FOUC dispone così del valore corretto dalla pagina successiva, su tutti i suoi dispositivi.

Utilizzo lato cliente

Pulsante nell’header

Il pulsante mostra un’icona in base alla modalità attiva: monitor (Auto), sole (Chiaro) o luna (Scuro). Ogni clic passa alla modalità successiva. Il cambio viene applicato istantaneamente con una transizione fluida e salvato in background.

Pagina profilo dell’account

In Il mio account → Profilo, una scheda «Aspetto» propone tre riquadri cliccabili (Auto, Chiaro, Scuro). La selezione viene salvata nell’account cliente e viene mostrato un messaggio di conferma. La navigazione da tastiera (Invio / Spazio) è supportata.

Personalizzazione

Spostare il pulsante dell’header

Per impostazione predefinita, il pulsante viene inserito nel block base_header_actions_wishlist. Per posizionarlo altrove, sovrascrivi il template di base nel tuo tema e includi il componente nel block che preferisci:

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

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

Reagire ai cambi di tema in JavaScript

Il plugin emette l’evento df-dark-mode-changed su document ad ogni cambio:

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

Utile per ricaricare una mappa, un grafico o qualsiasi componente di terze parti che non legge le variabili CSS.

Testi e traduzioni

Tutte le etichette sono snippet di Shopware (prefisso df-dark-mode.) modificabili nell’amministrazione, in Impostazioni → Snippet. Il plugin include francese, inglese e tedesco.

Riferimento tecnico

Custom field

All’installazione il plugin crea un set di custom field df_dark_mode contenente il campo df_dark_mode_preference (select: auto / light / dark) collegato all’entità customer. È visibile e modificabile nell’amministrazione sulla scheda del cliente.

Rotta AJAX

POST /df-dark-mode/save con il parametro mode (auto / light / dark). Imposta il cookie e, se un cliente è connesso, aggiorna il suo custom field. Risposta JSON.

Cookie

Nome: df-dark-mode · Valori: auto / light / dark · Durata: 365 giorni · SameSite=Lax. Cookie strettamente funzionale: non contiene dati personali né identificatori di tracciamento.

Disinstallazione

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

Alla disinstallazione, il set di custom field e le preferenze dei clienti vengono rimossi, a meno che l’opzione «conserva i dati» non sia selezionata.

Risoluzione dei problemi

Il pulsante non appare nell’header

Verifica che il tema sia stato ricompilato (bin/console theme:compile) e svuota la cache (bin/console cache:clear). Se il tuo tema sovrascrive pesantemente il block base_header_actions_wishlist, sposta l’include del componente in un altro block (vedi Personalizzazione).

La modalità scura si attiva ma i colori non cambiano

Il plugin imposta correttamente data-bs-theme="dark" (verificabile nell’ispettore del browser) ma il tuo CSS non definisce variabili sotto quel selettore. Aggiungi le tue variabili scure nel blocco [data-bs-theme="dark"] del tuo tema.

Lampo bianco al caricamento

Assicurati che nessun altro plugin sovrascriva il block base_head senza chiamare {{ parent() }}, cosa che rimuoverebbe lo script anti-FOUC.

La preferenza non viene mantenuta tra dispositivi

Solo i clienti connessi beneficiano della sincronizzazione multi-dispositivo tramite il loro account. Per i visitatori, la preferenza è locale al browser (cookie).

Changelog

1.0.0

• Versione iniziale: rilevamento del browser, pulsante nell’header, preferenza nell’account cliente, anti-FOUC, sincronizzazione al login, snippet FR/EN/DE.