# dfvariantswatch: swatches de variantes com fotografia e stock > Apresentação O dfvariantswatch substitui as listas pendentes de declinações das fichas de produto PrestaShop por miniaturas visuais clicáveis (fotografias, cores ou texto), mostra uma pré-visualização da variante na galeria principal… - Página: - Idioma: pt - Atualizado em: 2026-09-02 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfvariantswatch/index.md), [en](https://www.datafirefly.com/en/documentation/dfvariantswatch/index.md), [es](https://www.datafirefly.com/es/documentation/dfvariantswatch/index.md), [de](https://www.datafirefly.com/de/documentation/dfvariantswatch/index.md), [it](https://www.datafirefly.com/it/documentation/dfvariantswatch/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfvariantswatch/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfvariantswatch/index.md) - Índice: ## Apresentação O dfvariantswatch substitui as listas pendentes de declinações das fichas de produto PrestaShop por miniaturas visuais clicáveis (fotografias, cores ou texto), mostra uma pré-visualização da variante na galeria principal ao passar o rato e indica o stock de cada variante diretamente na miniatura. O módulo funciona melhorando os widgets nativos do PrestaShop via JavaScript: não substitui nenhum template do tema, o que o torna compatível com Classic, Hummingbird e a maioria dos temas premium. ## Instalação 1. Back-office → **Módulos** → **Gestor de módulos** → **Carregar um módulo** 2. Arraste e largue o arquivo `dfvariantswatch.zip` e clique em **Instalar** 3. Clique em **Configurar** para aceder às definições A instalação cria a tabela `df_variant_swatch`, a pasta de imagens `img/dfvariantswatch/` e os valores de configuração por defeito. Não é necessária nenhuma alteração do tema. Logo após a instalação, abra uma ficha de produto com declinações de cor: se as suas combinações tiverem fotografias, as miniaturas já aparecem: é a derivação automática. ## Funcionamento das miniaturas Para cada atributo, o módulo escolhe a fonte da miniatura por esta ordem de prioridade: 1. **Imagem carregada no back-office** para esse atributo (separador Miniaturas por atributo) 2. **Código de cor hexadecimal** definido no back-office 3. **Imagem derivada automaticamente** da primeira combinação que usa esse atributo 4. **Cor nativa do PrestaShop** do atributo (campo de cor do grupo) 5. **Pastilha de texto** com o nome do atributo ### A salvaguarda dos grupos não diferenciados A derivação automática só é conservada se as imagens diferirem realmente entre os atributos do grupo, ou se o grupo estiver marcado como grupo de cores no PrestaShop. Concretamente: num produto com um grupo Tamanho (S, M, L, XL) cujas combinações partilham todas as mesmas fotografias, os tamanhos ficam em pastilhas de texto em vez de mostrar quatro vezes a mesma fotografia. ## Configuração ### Parâmetros gerais - **Ativar o módulo**: corta a renderização no front-office sem desinstalar - **Passar o rato = mudança de galeria**: a pré-visualização da variante ao passar o rato numa miniatura - **Mostrar o badge de stock**: estado de disponibilidade sob cada miniatura - **Ocultar as variantes esgotadas**: esconde completamente as miniaturas esgotadas em vez de as riscar - **Forma**: redonda, quadrada ou pílula; **Tamanho** em píxeis - **Limiar de stock baixo**: abaixo dele, o badge passa ao estado de stock baixo - **Etiquetas de stock**: os três textos são personalizáveis e traduzíveis para português via Internacional → Traduções - **Modo de carregamento dos dados**: Inline (recomendado) ou AJAX, ver abaixo - **Grupos não renderizados em swatches**: os grupos selecionados conservam o seu widget nativo ### Miniaturas por atributo Este separador lista todos os grupos de atributos da loja. Para cada valor, pode carregar uma imagem (jpg, png, webp ou gif, 2 MB no máximo, 200 por 200 píxeis recomendado) ou introduzir um código de cor no formato #RRGGBB, pré-visualizar a miniatura atual e eliminar um swatch existente. ## Modos de carregamento **Inline (por defeito, recomendado)**: os dados das variantes são incorporados na página no momento da renderização. Nenhuma chamada AJAX no carregamento, apresentação imediata das miniaturas, robustez máxima. **AJAX**: os dados são recuperados através de uma chamada depois do carregamento da página. Reserve este modo às lojas atrás de uma cache full-page agressiva em que a frescura do stock apresentado prevalece sobre a velocidade de apresentação. ## Acessibilidade por teclado O seletor implementa o padrão WAI-ARIA radiogroup: a tecla Tab coloca o foco na variante selecionada do grupo (um único ponto de tabulação por grupo), as setas navegam e selecionam dentro do grupo em ciclo e saltando as variantes indisponíveis, Espaço ou Enter valida a miniatura focada. Os estados são anunciados aos leitores de ecrã via aria-checked e os balões respeitam prefers-reduced-motion. ## Personalização CSS As variáveis CSS expostas permitem ajustar a aparência a partir do CSS do seu tema filho sem tocar no módulo: ``` .dfvs-swatch { --dfvs-size: 56px; /* tamanho das miniaturas */ } .dfvs-swatch.dfvs-active { box-shadow: 0 0 0 2px #b8860b; /* anel da variante ativa */ } ``` Para desativar a pré-visualização ao passar o rato num produto preciso, adicione um elemento com o atributo `data-dfvs-disable-hover` no template de produto. ## Resolução de problemas ### As miniaturas não aparecem - Verifique que o módulo está ativado na sua configuração - Abra a consola do navegador: o módulo regista as suas etapas com o prefixo `[dfvariantswatch]`; verá o número de grupos renderizados ou o motivo da não renderização - O produto deve ter declinações; um produto simples não mostra nada, é normal ### Os tamanhos aparecem em texto e não em fotografia É o comportamento esperado da salvaguarda: os valores do grupo partilham as mesmas fotografias de combinações. Carregue imagens dedicadas por tamanho no separador Miniaturas por atributo se quiser visuais (por exemplo pictogramas de silhueta). ### O bloco nativo reaparece depois de um clique O módulo reaplica a ocultação depois de cada atualização AJAX do PrestaShop. Se um tema muito personalizado contornar os eventos padrão, contacte o suporte com o URL da ficha de produto em causa. ## Desinstalação A desinstalação elimina a tabela do módulo, as imagens carregadas em `img/dfvariantswatch/` e todas as chaves de configuração. As fotografias das suas combinações não são, evidentemente, afetadas.