Melhores Práticas de Animação GSAP
Guia abrangente para implementar animações profissionais, acessíveis e de alto desempenho usando GSAP (GreenSock Animation Platform).
Princípios Fundamentais
1. Performance em Primeiro Lugar
- Anime apenas
transformeopacity(acelerados por GPU) - Evite animar
width,height,top,left,margin,padding - Use
will-changecom moderação - Busque 60fps em todos os dispositivos
2. Acessibilidade Sempre
- Respeite
prefers-reduced-motion - Garanta que o conteúdo seja visível sem JavaScript
- Não esconda conteúdo crítico atrás de animações
- Forneça controles de pular/pausar para animações longas
3. Aprimoramento Progressivo
- O conteúdo deve funcionar sem animações
- Animações melhoram, não substituem, a funcionalidade
- Teste com animações desabilitadas
Configuração do GSAP
Instalação
<!-- CDN (recomendado para WordPress) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>
<!-- Plugins opcionais -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollSmoother.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/SplitText.min.js"></script>
Enfileiramento no WordPress
function theme_enqueue_gsap() {
// GSAP Core
wp_enqueue_script(
'gsap',
'https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js',
array(),
'3.12.5',
true
);
// ScrollTrigger
wp_enqueue_script(
'gsap-scrolltrigger',
'https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js',
array('gsap'),
'3.12.5',
true
);
// Animações do tema
wp_enqueue_script(
'theme-animacoes',
get_theme_file_uri('/assets/js/animacoes.js'),
array('gsap', 'gsap-scrolltrigger'),
filemtime(get_theme_file_path('/assets/js/animacoes.js')),
true
);
}
add_action('wp_enqueue_scripts', 'theme_enqueue_gsap');
Padrões de Animação
1. Fade In ao Rolar
// Fade in básico
gsap.from('.fade-in', {
opacity: 0,
y: 50,
duration: 1,
stagger: 0.2,
scrollTrigger: {
trigger: '.fade-in',
start: 'top 80%',
toggleActions: 'play none none none'
}
});
2. Elementos Escalonados
// Cartões aparecendo um por um
gsap.from('.cartao', {
opacity: 0,
y: 100,
duration: 0.8,
stagger: {
amount: 0.6,
from: 'start'
},
ease: 'power2.out',
scrollTrigger: {
trigger: '.cartoes-container',
start: 'top 75%'
}
});
3. Efeito Paralaxe
// Paralaxe sutil em imagens
gsap.to('.imagem-paralaxe', {
yPercent: -20,
ease: 'none',
scrollTrigger: {
trigger: '.secao-paralaxe',
start: 'top bottom',
end: 'bottom top',
scrub: true
}
});
4. Revelação de Texto (Linha por Linha)
// Requer plugin SplitText (Club GreenSock)
// Ou use a alternativa baseada em CSS abaixo
// Alternativa CSS - envolva cada linha em um span
gsap.from('.linha-revelada', {
opacity: 0,
y: '100%',
duration: 0.8,
stagger: 0.1,
ease: 'power3.out',
scrollTrigger: {
trigger: '.texto-revelado',
start: 'top 80%'
}
});
5. Revelação com Máscara/Cortina
// Imagem revelada por máscara deslizante
gsap.to('.mascara-cortina', {
scaleX: 0,
transformOrigin: 'right center',
duration: 1.2,
ease: 'power4.inOut',
scrollTrigger: {
trigger: '.container-cortina',
start: 'top 70%'
}
});
6. Timeline de Animação Hero
// Sequência hero complexa
const heroTL = gsap.timeline({
defaults: { ease: 'power3.out' }
});
heroTL
.from('.hero-bg', { scale: 1.2, duration: 1.5 })
.from('.hero-titulo', { opacity: 0, y: 100, duration: 1 }, '-=1')
.from('.hero-subtitulo', { opacity: 0, y: 50, duration: 0.8 }, '-=0.5')
.from('.hero-cta', { opacity: 0, y: 30, duration: 0.6 }, '-=0.3');
Acessibilidade
Respeitar Movimento Reduzido
// Verificar preferência do usuário
const prefereMovimentoReduzido = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
// Opção 1: Desabilitar todas as animações
if (prefereMovimentoReduzido) {
gsap.globalTimeline.timeScale(0);
ScrollTrigger.getAll().forEach(st => st.kill());
}
// Opção 2: Animações simplificadas
const configAnimacao = prefereMovimentoReduzido
? { duration: 0, stagger: 0 }
: { duration: 1, stagger: 0.2 };
gsap.from('.elemento', {
opacity: 0,
y: prefereMovimentoReduzido ? 0 : 50,
...configAnimacao
});
Fallback CSS
/* Garantir conteúdo visível sem JS */
.fade-in {
opacity: 1;
transform: translateY(0);
}
/* Ocultar apenas se as animações forem executar */
.js .fade-in {
opacity: 0;
transform: translateY(50px);
}
/* Respeitar movimento reduzido também no CSS */
@media (prefers-reduced-motion: reduce) {
.js .fade-in {
opacity: 1;
transform: none;
}
}
Adicionar Classe JS ao HTML
// Adicionar no início do script
document.documentElement.classList.add('js');
Animações Responsivas
Animações Sensíveis a Breakpoints
// Criar animações responsivas
const mm = gsap.matchMedia();
mm.add('(min-width: 1024px)', () => {
// Animações para desktop
gsap.from('.imagem-hero', {
x: 100,
opacity: 0,
duration: 1.2
});
return () => {
// Limpeza na mudança de breakpoint
};
});
mm.add('(max-width: 1023px)', () => {
// Animações para mobile (mais simples)
gsap.from('.imagem-hero', {
opacity: 0,
duration: 0.8
});
});
Atualizar ao Redimensionar
// Recalcular ScrollTrigger ao redimensionar
let timerRedimensionar;
window.addEventListener('resize', () => {
clearTimeout(timerRedimensionar);
timerRedimensionar = setTimeout(() => {
ScrollTrigger.refresh();
}, 250);
});
Otimização de Performance
1. Usar Apenas Propriedades de Transformação
// BOM - Acelerado por GPU
gsap.to('.elemento', {
x: 100, // transform: translateX
y: 50, // transform: translateY
rotation: 45, // transform: rotate
scale: 1.2, // transform: scale
opacity: 0.5
});
// RUIM - Causa layout/paint
gsap.to('.elemento', {
left: 100, // Dispara layout
width: '200px', // Dispara layout
marginTop: 50 // Dispara layout
});
2. Agrupar Animações Semelhantes
// Use batch para muitos elementos semelhantes
ScrollTrigger.batch('.cartao', {
onEnter: batch => gsap.to(batch, {
opacity: 1,
y: 0,
stagger: 0.1
}),
start: 'top 85%'
});
3. Eliminar ScrollTriggers Não Utilizados
// Limpeza ao navegar (SPA) ou desmontar componente
function limpar() {
ScrollTrigger.getAll().forEach(st => st.kill());
gsap.killTweensOf('*');
}
4. Inicialização Preguiçosa
// Inicializar animações apenas para seções visíveis
const observador = new IntersectionObserver((entradas) => {
entradas.forEach(entrada => {
if (entrada.isIntersecting) {
iniciarAnimacoesSecao(entrada.target);
observador.unobserve(entrada.target);
}
});
}, { rootMargin: '100px' });
document.querySelectorAll('.secao-animada').forEach(secao => {
observador.observe(secao);
});
Melhores Práticas do ScrollTrigger
1. Pontos de Início/Fim Adequados
// Evitar erros comuns
ScrollTrigger.create({
trigger: '.secao',
start: 'top 80%', // Quando o topo do trigger atinge 80% do topo da viewport
end: 'bottom 20%', // Quando o fundo do trigger atinge 20% do topo
markers: true, // Apenas para depuração - remover em produção!
});
2. Fixar Seções com Cuidado
// Fixar pode causar problemas de layout
ScrollTrigger.create({
trigger: '.secao-fixada',
start: 'top top',
end: '+=100%',
pin: true,
pinSpacing: true, // Geralmente queremos isso verdadeiro
anticipatePin: 1 // Ajuda em dispositivos móveis
});
3. Lidar com Carregamento de Imagens
// Aguardar imagens antes de calcular posições
ScrollTrigger.config({
ignoreMobileResize: true
});
window.addEventListener('load', () => {
ScrollTrigger.refresh();
});
// Ou atualizar após imagens lazy carregarem
document.querySelectorAll('img[loading="lazy"]').forEach(img => {
img.addEventListener('load', () => ScrollTrigger.refresh());
});
Integração de Testes
Compatibilidade com Visual QA
Para que o skill visual-qa capture as animações corretamente:
// Expor função para completar todas as animações instantaneamente
window.completarTodasAnimacoes = function() {
gsap.globalTimeline.progress(1);
ScrollTrigger.getAll().forEach(st => {
st.scroll(st.end);
});
};
// Ou pular animações inteiramente para capturas de tela
if (window.location.search.includes('pular-animacoes')) {
gsap.globalTimeline.timeScale(100);
}
Testes com Playwright
// Em teste Playwright
await page.evaluate(() => {
if (window.completarTodasAnimacoes) {
window.completarTodasAnimacoes();
}
});
await page.waitForTimeout(500);
await page.screenshot({ path: 'captura.png', fullPage: true });
Biblioteca de Animação Comum
Classes de Animação Reutilizáveis
// animacoes.js - Biblioteca de animação reutilizável
const Animacoes = {
// Inicializar todas as animações
init() {
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
return;
}
this.fadeIn();
this.slideIn();
this.paralaxe();
this.textoRevelado();
},
fadeIn() {
gsap.utils.toArray('[data-animar="fade-in"]').forEach(el => {
gsap.from(el, {
opacity: 0,
y: 50,
duration: 0.8,
scrollTrigger: {
trigger: el,
start: 'top 85%',
once: true
}
});
});
},
slideIn() {
gsap.utils.toArray('[data-animar="slide-esquerda"]').forEach(el => {
gsap.from(el, {
opacity: 0,
x: -100,
duration: 1,
scrollTrigger: {
trigger: el,
start: 'top 80%',
once: true
}
});
});
gsap.utils.toArray('[data-animar="slide-direita"]').forEach(el => {
gsap.from(el, {
opacity: 0,
x: 100,
duration: 1,
scrollTrigger: {
trigger: el,
start: 'top 80%',
once: true
}
});
});
},
paralaxe() {
gsap.utils.toArray('[data-paralaxe]').forEach(el => {
const velocidade = el.dataset.paralaxe || 0.2;
gsap.to(el, {
yPercent: -100 * velocidade,
ease: 'none',
scrollTrigger: {
trigger: el.parentElement,
start: 'top bottom',
end: 'bottom top',
scrub: true
}
});
});
},
textoRevelado() {
gsap.utils.toArray('[data-animar="texto-revelado"]').forEach(el => {
const linhas = el.querySelectorAll('.linha');
gsap.from(linhas, {
opacity: 0,
y: '100%',
duration: 0.8,
stagger: 0.1,
scrollTrigger: {
trigger: el,
start: 'top 80%',
once: true
}
});
});
},
// Atualizar após conteúdo dinâmico
atualizar() {
ScrollTrigger.refresh();
},
// Limpeza para navegação SPA
destruir() {
ScrollTrigger.getAll().forEach(st => st.kill());
gsap.killTweensOf('*');
}
};
// Inicializar quando DOM estiver pronto
document.addEventListener('DOMContentLoaded', () => Animacoes.init());
Uso em HTML
<!-- Fade in -->
<div data-animar="fade-in">Conteúdo</div>
<!-- Slide da esquerda -->
<div data-animar="slide-esquerda">Conteúdo</div>
<!-- Paralaxe (0.2 = 20% de velocidade) -->
<img data-paralaxe="0.3" src="imagem.jpg">
<!-- Revelação de texto (requer quebra de linha) -->
<div data-animar="texto-revelado">
<div class="linha">Primeira linha</div>
<div class="linha">Segunda linha</div>
</div>
Depuração
Habilitar Marcadores
ScrollTrigger.defaults({
markers: true // Mostra marcadores de início/fim
});
Registrar Eventos de Animação
gsap.to('.elemento', {
x: 100,
onStart: () => console.log('Animação iniciada'),
onComplete: () => console.log('Animação concluída'),
onUpdate: self => console.log('Progresso:', self.progress())
});
Verificar Problemas
// Listar todos os ScrollTriggers
console.log('ScrollTriggers:', ScrollTrigger.getAll());
// Verificar se o elemento existe
const el = document.querySelector('.elemento-animado');
if (!el) console.warn('Alvo da animação não encontrado!');
Checklist
Antes do Lançamento
- Remover todos os
markers: true - Testar com
prefers-reduced-motion: reduce - Testar em dispositivos móveis (dispositivos reais, não apenas DevTools)
- Verificar desempenho na aba Performance do DevTools
- Verificar 60fps nos dispositivos alvo
- Conteúdo visível sem JavaScript
- Imagens lazy-loaded antes da atualização do ScrollTrigger
- Sem thrashing de layout (evitar animar propriedades de layout)
Integração Visual QA
- Animações concluídas antes das capturas de tela
- Rolagem de página completa dispara todas as animações
- Capturas de tela capturam o estado final animado
- Testar em todos os tamanhos de viewport
Recursos
- Documentação GSAP
- [Documentação ScrollTrigger](https://greensock.com/docs/v3/Plugins/Scr
[truncated]
