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

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.

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.