DfDarkMode: modo escuro para Shopware 6.7

Apresentação

O DfDarkMode acrescenta um modo escuro completo ao storefront do Shopware 6.7. A extensão aplica o atributo data-bs-theme na etiqueta raiz html da página: as suas variáveis CSS declaradas sob [data-bs-theme="dark"] ativam-se automaticamente, sem qualquer alteração ao seu tema.

• Deteção automática da definição prefers-color-scheme do navegador (modo Auto)
• Botão no cabeçalho: um botão que alterna entre Auto → Claro → Escuro
• Preferência do cliente: seletor visual na página de perfil da conta de cliente
• Persistência dupla: cookie para os visitantes, campo próprio de cliente para as contas com sessão iniciada
• Anti-FOUC: o tema é aplicado antes da renderização da página, sem clarão branco
• Sincronização no início de sessão: a preferência da conta é restaurada automaticamente ao iniciar sessão

Pré-requisitos

• Shopware 6.7.0 ou superior
• Um tema cujas cores estejam definidas por variáveis CSS sob [data-bs-theme="dark"] (convenção Bootstrap 5.3)

Instalação

1. Copie a pasta DfDarkMode para custom/plugins/ da sua instalação Shopware.
2. Execute os seguintes comandos:

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

Depois da compilação do tema, o botão de alternância aparece no cabeçalho do storefront e o cartão «Aparência» surge na página de perfil da conta de cliente.

Funcionamento

Os três modos

• Auto (predefinição): segue a definição do navegador ou do sistema operativo. Se o utilizador passar o sistema a escuro, o storefront acompanha em tempo real.
• Claro: força o modo claro seja qual for o navegador.
• Escuro: força o modo escuro seja qual for o navegador.

Ordem de prioridade da preferência

1. Cliente com sessão iniciada: o campo próprio df_dark_mode_preference da conta de cliente prevalece sobre tudo.
2. Visitante: o cookie df-dark-mode (validade de 1 ano).
3. Sem preferência: modo Auto.

Anti-FOUC

Um script inline colocado no head lê o cookie e aplica data-bs-theme antes de o navegador pintar a página. Resultado: nenhum clarão de fundo claro no carregamento em modo escuro, mesmo com uma ligação lenta.

Sincronização no início de sessão

Quando um cliente inicia sessão, a sua preferência guardada é copiada para o cookie. O script anti-FOUC dispõe assim do valor certo logo na página seguinte, em todos os dispositivos dele.

Utilização do lado do cliente

Botão do cabeçalho

O botão mostra um ícone consoante o modo ativo: monitor (Auto), sol (Claro) ou lua (Escuro). Cada clique passa ao modo seguinte. A alteração é aplicada instantaneamente com uma transição suave e guardada em segundo plano.

Página de perfil da conta

Em A minha conta → Perfil, um cartão «Aparência» oferece três miniaturas clicáveis (Auto, Claro, Escuro). A seleção é guardada na conta de cliente e aparece uma mensagem de confirmação. A navegação por teclado (Enter / Espaço) é suportada.

Personalização

Mover o botão do cabeçalho

Por predefinição, o botão é injetado no bloco base_header_actions_wishlist. Para o colocar noutro sítio, sobreponha o template de base no seu tema e inclua o componente no bloco à sua escolha:

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

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

Reagir às mudanças de tema em JavaScript

A extensão emite o evento df-dark-mode-changed em document a cada alteração:

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

Útil para recarregar um mapa, um gráfico ou qualquer componente de terceiros que não leia as variáveis CSS.

Textos e traduções

Todas as etiquetas são snippets do Shopware (prefixo df-dark-mode.) alteráveis na administração, em Definições → Snippets. A extensão inclui o francês, o inglês e o alemão.

Referência técnica

Campo próprio

Na instalação, a extensão cria um conjunto de campos próprios df_dark_mode com o campo df_dark_mode_preference (select: auto / light / dark) associado à entidade customer. É visível e modificável na administração, na ficha do cliente.

Rota AJAX

POST /df-dark-mode/save com o parâmetro mode (auto / light / dark). Coloca o cookie e, se houver um cliente com sessão iniciada, atualiza o seu campo próprio. Resposta em JSON.

Cookie

Nome: df-dark-mode · Valores: auto / light / dark · Duração: 365 dias · SameSite=Lax. Cookie estritamente funcional: não contém qualquer dado pessoal nem identificador de seguimento.

Desinstalação

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

Na desinstalação, o conjunto de campos próprios e as preferências dos clientes são eliminados, exceto se a opção «conservar os dados» estiver marcada.

Resolução de problemas

O botão não aparece no cabeçalho

Verifique que o tema foi mesmo recompilado (bin/console theme:compile) e limpe a cache (bin/console cache:clear). Se o seu tema sobrepuser fortemente o bloco base_header_actions_wishlist, mova o include do componente para outro bloco (ver Personalização).

O modo escuro ativa-se mas as cores não mudam

A extensão coloca corretamente data-bs-theme="dark" (verificável no inspetor do navegador) mas o seu CSS não define variáveis sob esse seletor. Acrescente as suas variáveis escuras no bloco [data-bs-theme="dark"] do seu tema.

Clarão branco no carregamento

Confirme que nenhuma outra extensão sobrepõe o bloco base_head sem chamar {{ parent() }}, o que eliminaria o script anti-FOUC.

A preferência não é mantida entre dispositivos

Só os clientes com sessão iniciada beneficiam da sincronização entre dispositivos através da conta. Para os visitantes, a preferência é local ao navegador (cookie).

Changelog

1.0.0

• Versão inicial: deteção do navegador, botão no cabeçalho, preferência na conta de cliente, anti-FOUC, sincronização no início de sessão, snippets FR/EN/DE.