# Sticky Add to Cart para PrestaShop: guia completo

> Apresentação O DataFirefly Sticky Add to Cart apresenta uma barra «Adicionar ao carrinho» persistente nas páginas de produto da sua loja PrestaShop 8 ou 9. Em telemóvel, uma barra compacta…

- Página: <https://www.datafirefly.com/pt/documentation/dfstickyaddtocart/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfstickyaddtocart/index.md), [en](https://www.datafirefly.com/en/documentation/dfstickyaddtocart/index.md), [es](https://www.datafirefly.com/es/documentation/dfstickyaddtocart/index.md), [de](https://www.datafirefly.com/de/documentation/dfstickyaddtocart/index.md), [it](https://www.datafirefly.com/it/documentation/dfstickyaddtocart/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfstickyaddtocart/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfstickyaddtocart/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Apresentação

O DataFirefly Sticky Add to Cart apresenta uma barra «Adicionar ao carrinho» persistente nas páginas de produto da sua loja PrestaShop 8 ou 9. Em telemóvel, uma barra compacta fixa-se no fundo do ecrã. Em computador, uma barra lateral flutuante desliza a partir da direita (ou, à sua escolha, uma barra no fundo idêntica à de telemóvel). A barra inclui um seletor compacto de variante, um seletor de quantidade e o preço atualizado em tempo real.

A adição ao carrinho é feita por um pedido AJAX direto ao controlador de carrinho do PrestaShop: o módulo nunca manipula o formulário nem o botão nativo do seu tema, o que garante uma coexistência sem conflitos.

## Instalação

1. No seu back-office PrestaShop, abra **Módulos > Gestor de módulos**.
2. Clique em **Carregar um módulo** e selecione o ficheiro `dfstickyaddtocart.zip`.
3. Depois de instalado o módulo, clique em **Configurar**.
4. Limpe a cache do PrestaShop: **Parâmetros avançados > Desempenho > Limpar cache**.

**Pré-requisitos**: PrestaShop 8.0 a 9.x e PHP 8.1 ou superior. Sem dependências externas e sem necessidade de alterar o tema.

## Configuração

Todas as definições estão em **Módulos > Gestor de módulos > DataFirefly Sticky Add to Cart > Configurar**.

### Apresentação

- **Ativar o módulo**: interruptor global.
- **Mostrar em telemóvel**: ativa a barra no fundo em ecrãs com menos de 992 px.
- **Mostrar em computador**: ativa a apresentação em ecrãs de 992 px ou mais.
- **Apresentação em computador**: dois modos, _Barra lateral flutuante (à direita)_, um cartão de 320 px que desliza a partir da margem direita, ou _Barra no fundo_, idêntica ao resultado em telemóvel mas centrada em 1280 px.
- **Desvio superior em computador (px)**: distância entre o topo da janela e a barra lateral flutuante. Aumente este valor se o seu tema tiver um cabeçalho fixo (90 px por predefinição).

### Conteúdo da barra

- **Mostrar a imagem do produto**: miniatura da imagem de capa.
- **Mostrar o seletor de variante**: lista pendente compacta das combinações (ocultada automaticamente se o produto não tiver combinações).
- **Mostrar o seletor de quantidade**: botões de menos e mais (apresentado em computador; em telemóvel, a quantidade fica em 1 para preservar a compacidade).
- **Ocultar quando o botão principal está visível**: a barra só aparece quando o botão «Adicionar ao carrinho» original sai do viewport (recomendado). Desative para ter uma barra permanentemente visível.

### Cores

- **Cor de fundo**: fundo da barra (branco por predefinição).
- **Cor do botão**: botão de adição ao carrinho (azul-turquesa `#2fb5d2` por predefinição).
- **Cor do texto do botão**: designação do botão.
- **Cor do texto**: nome do produto e designações.
- **Cor do preço**: opcional; se ficar vazia, é usada a cor do botão.

As cores são injetadas como variáveis CSS (`--dfs-bg`, `--dfs-btn`, `--dfs-btn-text`, `--dfs-text`, `--dfs-price`). Pode sobrepô-las na folha de estilo do seu tema, para um controlo avançado.

## Funcionamento

### Deteção de visibilidade

O módulo observa o bloco «Adicionar ao carrinho» original com a API IntersectionObserver do navegador. Assim que esse bloco sai do viewport (o utilizador desceu na página), a barra fixa aparece com uma animação de deslize. Assim que volta a ficar visível, a barra desaparece. Este mecanismo é nativo do navegador e não acrescenta qualquer custo de desempenho ao deslocamento.

### Seletor de variante

Nos produtos com combinações, o seletor compacto mostra cada combinação com o seu preço e a sua disponibilidade (as combinações em rutura ficam desativadas). A seleção é local à barra fixa: não altera a interface de variantes da página principal. Quando o cliente muda de variante a partir da página principal, a barra fixa sincroniza-se automaticamente através do evento `updatedProduct` do PrestaShop.

### Adição ao carrinho

O clique no botão fixo envia um pedido AJAX `POST` diretamente ao controlador de carrinho do PrestaShop (o mesmo endpoint do tema), com a combinação e a quantidade escolhidas na barra. Em caso de sucesso, o módulo emite o evento `updateCart`: o contador do carrinho no cabeçalho e a pré-visualização do carrinho do seu tema atualizam-se normalmente, e o botão fixo mostra uma marca de confirmação.

O módulo nunca clica no botão nativo do seu tema nem altera o seu formulário. Os dois botões funcionam de forma totalmente independente.

## Apresentação em telemóvel

Em telemóvel, a barra adapta-se automaticamente:

- **Produto sem variantes**: uma só linha, com miniatura, nome, preço e botão. Abaixo dos 600 px, a designação do botão dá lugar ao ícone de carrinho; abaixo dos 380 px, a miniatura é ocultada.
- **Produto com variantes**: duas linhas, com miniatura, nome, preço e botão na primeira, e o seletor de variante em largura total na segunda.

A barra respeita a zona `safe-area-inset-bottom` dos iPhone com entalhe e a preferência `prefers-reduced-motion` dos utilizadores sensíveis às animações.

Em português, «Adicionar ao carrinho» é bastante mais longo do que o equivalente inglês. Se a barra ficar apertada num telemóvel pequeno, aproveite o modo com ícone abaixo dos 600 px, ou encurte a designação do botão para «Comprar» através das traduções.

## Compatibilidade com o tema

O módulo visa os seletores CSS padrão do tema Classic e dos seus derivados: `.product-add-to-cart`, `.add-to-cart`, `button[data-button-action="add-to-cart"]` e `form#add-to-cart-or-refresh`. A grande maioria dos temas do mercado segue estas convenções.

Se o seu tema usar classes diferentes, há duas funções a adaptar no início do ficheiro `views/js/dfstickyaddtocart.js`: `getMainBtn()` (seletor do botão nativo) e `getMainForm()` (seletor do formulário de produto). São os dois únicos pontos de contacto com o seu tema.

## Resolução de problemas

### A barra não aparece

1. Confirme que o módulo está ativo na sua configuração e que a apresentação está ativa para o dispositivo testado (telemóvel ou computador).
2. Limpe a cache do PrestaShop (**Parâmetros avançados > Desempenho**) e recarregue a página com Ctrl+Shift+R.
3. Se a opção «Ocultar quando o botão principal está visível» estiver ativa, a barra só aparece depois de descer para lá do botão original: é o comportamento esperado.
4. Verifique na consola do navegador que nenhum erro de JavaScript de outro módulo está a bloquear a execução da página.

### A adição ao carrinho não funciona

1. Abra a consola do navegador: o módulo regista aí os seus erros com o prefixo `[dfsticky]`.
2. Verifique no separador Rede o pedido `POST` para o controlador de carrinho: o código HTTP e o corpo da resposta indicam a causa exata (rutura de stock, quantidade mínima, entre outras).
3. O módulo tolera os avisos do PHP em ambiente de desenvolvimento (extrai o JSON mesmo quando é precedido de avisos), mas continua a recomendar-se um ambiente de produção limpo.

### A barra lateral sobrepõe-se ao cabeçalho do tema

Aumente o valor de **Desvio superior em computador (px)** na configuração, até a barra lateral se posicionar por baixo do seu cabeçalho fixo.

## Perguntas frequentes técnicas

### O módulo torna as páginas mais lentas?

Não. Os recursos (cerca de 7 KB de CSS e 12 KB de JavaScript) só são carregados no controlador `product`. Sem bibliotecas externas e sem listeners de deslocamento: a visibilidade é gerida pelo IntersectionObserver.

### É compatível com multiloja?

Sim. Todos os valores são guardados pela classe `Configuration` do PrestaShop, com o contexto multiloja nativo: cada loja pode ter as suas próprias cores e definições.

### Que hooks são utilizados?

`actionFrontControllerSetMedia` (registo dos recursos), `displayFooterProduct` (apresentação da marcação) e `displayHeader` (micro-CSS crítico contra o efeito de intermitência).

### Os textos são traduzíveis?

Sim. Todas as cadeias passam pelo sistema de tradução do PrestaShop. O módulo é entregue em francês, inglês, espanhol e alemão; acrescente outros idiomas em **Internacional > Traduções**.

O português não está incluído no pacote. Como o texto do botão e as designações da barra são vistos pelo cliente na ficha de produto, traduza-os antes de ativar o módulo numa loja portuguesa.

## Registo de versões

### 1.0.3

- Análise tolerante das respostas do controlador de carrinho: o JSON é corretamente extraído mesmo quando é precedido de avisos do PHP (ambientes de desenvolvimento).
- Corpo do pedido em formato URL-encoded, igual à serialização nativa do tema, para máxima compatibilidade.
- Eliminação definitiva de qualquer acionamento programático do botão nativo: os dois botões passam a ser totalmente independentes.

### 1.0.2

- Eliminação da apresentação da janela de confirmação devolvida pelo controlador de carrinho, que podia deixar uma camada invisível a bloquear os cliques em algumas páginas. A confirmação passa pelo evento `updateCart` e pela marca no botão fixo.
- Limpeza defensiva das janelas órfãs no carregamento da página.

### 1.0.1

- Passagem à adição ao carrinho por pedido AJAX direto: o módulo deixa de alterar o formulário de produto e de depender do estado do DOM do tema.
- Referências do DOM resolvidas no momento, para resistir à substituição do formulário pelo motor de combinações.
- Reinicialização de segurança do indicador de carregamento.

### 1.0.0

- Versão inicial: barra fixa em telemóvel e computador, seletor compacto de variante, seletor de quantidade, personalização de cores, acessibilidade ARIA, multiloja e FR/EN/ES/DE.