# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/dfdarkmode/>
- Lingua: it
- Aggiornato il: 2026-07-22
- Altre lingue: [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), [pl](https://www.datafirefly.com/pl/documentation/dfdarkmode/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdarkmode/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdarkmode/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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

Il plugin non fornisce una palette scura: gestisce esclusivamente l'attributo `data-bs-theme`. Il CSS della modalità scura deve già esistere nel tema.

## 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.

In ambiente di sviluppo, usa `bin/console theme:compile --active-only` o il watcher dello storefront per la ricompilazione a caldo.

## 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.