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

- Página: <https://www.datafirefly.com/pt/documentation/dfdarkmode/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [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), [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)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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

A extensão não fornece uma paleta escura: controla apenas o atributo `data-bs-theme`. O seu CSS de modo escuro tem de existir já no tema.

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

Em ambiente de desenvolvimento, use `bin/console theme:compile --active-only` ou o watcher do storefront para recompilar em direto.

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