# DfDarkMode – Modo oscuro para Shopware 6.7

> Presentación DfDarkMode añade un modo oscuro completo al storefront de Shopware 6.7. El plugin aplica el atributo data-bs-theme en la etiqueta raíz html de la página: tus variables CSS declaradas…

- Página: <https://www.datafirefly.com/es/documentation/dfdarkmode/>
- Idioma: es
- Actualizado el: 2026-07-22
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/dfdarkmode/index.md), [en](https://www.datafirefly.com/en/documentation/dfdarkmode/index.md), [de](https://www.datafirefly.com/de/documentation/dfdarkmode/index.md), [it](https://www.datafirefly.com/it/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)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## Presentación

DfDarkMode añade un modo oscuro completo al storefront de Shopware 6.7. El plugin aplica el atributo `data-bs-theme` en la etiqueta raíz html de la página: tus variables CSS declaradas bajo `[data-bs-theme="dark"]` se activan automáticamente, sin ningún cambio en tu tema.

- **Detección automática** del ajuste `prefers-color-scheme` del navegador (modo Auto)
- **Botón en el header**: un botón que alterna entre Auto → Claro → Oscuro
- **Preferencia del cliente**: selector visual en la página de perfil de la cuenta
- **Persistencia doble**: cookie para visitantes, custom field de cliente para cuentas conectadas
- **Anti-FOUC**: el tema se aplica antes de renderizar la página, sin destello blanco
- **Sincronización al iniciar sesión**: la preferencia de la cuenta se restaura automáticamente

## Requisitos

- Shopware 6.7.0 o superior
- Un tema cuyos colores estén definidos mediante variables CSS bajo `[data-bs-theme="dark"]` (convención Bootstrap 5.3)

El plugin no incluye una paleta oscura: solo controla el atributo `data-bs-theme`. Tu CSS de modo oscuro debe existir previamente en el tema.

## Instalación

1. Copia la carpeta `DfDarkMode` en `custom/plugins/` de tu instalación Shopware.
2. Ejecuta los siguientes comandos:

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

Tras compilar el tema, el botón de cambio aparece en el header del storefront y la tarjeta «Apariencia» se muestra en la página de perfil de la cuenta del cliente.

En entorno de desarrollo, usa `bin/console theme:compile --active-only` o el watcher del storefront para recompilar en caliente.

## Funcionamiento

### Los tres modos

- **Auto** (por defecto): sigue el ajuste del navegador o del sistema operativo. Si el usuario cambia su SO a oscuro, el storefront le sigue en tiempo real.
- **Claro**: fuerza el modo claro sea cual sea el navegador.
- **Oscuro**: fuerza el modo oscuro sea cual sea el navegador.

### Orden de prioridad de la preferencia

1. **Cliente conectado**: el custom field `df_dark_mode_preference` de la cuenta prevalece sobre todo.
2. **Visitante**: la cookie `df-dark-mode` (duración de 1 año).
3. **Sin preferencia**: modo Auto.

### Anti-FOUC

Un script inline colocado en la etiqueta head lee la cookie y aplica `data-bs-theme` antes de que el navegador pinte la página. Resultado: ningún destello de fondo claro al cargar en modo oscuro, incluso con conexión lenta.

### Sincronización al iniciar sesión

Al conectarse un cliente, su preferencia guardada se copia en la cookie. El script anti-FOUC dispone así del valor correcto desde la página siguiente, en todos sus dispositivos.

## Uso por parte del cliente

### Botón del header

El botón muestra un icono según el modo activo: monitor (Auto), sol (Claro) o luna (Oscuro). Cada clic pasa al modo siguiente. El cambio se aplica al instante con una transición suave y se guarda en segundo plano.

### Página de perfil de la cuenta

En **Mi cuenta → Perfil**, una tarjeta «Apariencia» ofrece tres opciones clicables (Auto, Claro, Oscuro). La selección se guarda en la cuenta del cliente y se muestra un mensaje de confirmación. Se admite la navegación por teclado (Intro / Espacio).

## Personalización

### Mover el botón del header

Por defecto, el botón se inyecta en el block `base_header_actions_wishlist`. Para colocarlo en otro lugar, sobrescribe la plantilla base en tu tema e incluye el componente en el block que prefieras:

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

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

### Reaccionar a los cambios de tema en JavaScript

El plugin emite el evento `df-dark-mode-changed` en `document` con cada 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'
});
```

Útil para recargar un mapa, un gráfico o cualquier componente de terceros que no lea las variables CSS.

### Textos y traducciones

Todas las etiquetas son snippets de Shopware (prefijo `df-dark-mode.`) editables en la administración, en **Ajustes → Snippets**. El plugin incluye francés, inglés y alemán.

## Referencia técnica

### Custom field

Al instalarse, el plugin crea un conjunto de custom fields `df_dark_mode` con el campo `df_dark_mode_preference` (select: auto / light / dark) vinculado a la entidad customer. Es visible y editable en la administración en la ficha del cliente.

### Ruta AJAX

`POST /df-dark-mode/save` con el parámetro `mode` (auto / light / dark). Establece la cookie y, si hay un cliente conectado, actualiza su custom field. Respuesta JSON.

### Cookie

Nombre: `df-dark-mode` · Valores: auto / light / dark · Duración: 365 días · SameSite=Lax. Cookie estrictamente funcional: no contiene datos personales ni identificadores de seguimiento.

## Desinstalación

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

Al desinstalar, el conjunto de custom fields y las preferencias de los clientes se eliminan, salvo que la opción «conservar los datos» esté marcada.

## Solución de problemas

### El botón no aparece en el header

Comprueba que el tema se ha recompilado (`bin/console theme:compile`) y vacía la caché (`bin/console cache:clear`). Si tu tema sobrescribe intensamente el block `base_header_actions_wishlist`, mueve el include del componente a otro block (ver Personalización).

### El modo oscuro se activa pero los colores no cambian

El plugin sí establece `data-bs-theme="dark"` (verificable en el inspector del navegador) pero tu CSS no define variables bajo ese selector. Añade tus variables oscuras al bloque `[data-bs-theme="dark"]` de tu tema.

### Destello blanco al cargar

Asegúrate de que ningún otro plugin sobrescriba el block `base_head` sin llamar a `{{ parent() }}`, lo que eliminaría el script anti-FOUC.

### La preferencia no se conserva entre dispositivos

Solo los clientes conectados disfrutan de la sincronización multidispositivo a través de su cuenta. Para los visitantes, la preferencia es local al navegador (cookie).

## Changelog

### 1.0.0

- Versión inicial: detección del navegador, botón en el header, preferencia en la cuenta del cliente, anti-FOUC, sincronización al iniciar sesión, snippets FR/EN/DE.