Carousel Carrossel
Introdução
O componente Carousel é uma apresentação de slides de alto desempenho com rolagem nativa que pagina através de um conjunto de slides. Criado especificamente para a construção de páginas no CMS e com renderização estática sem JS por padrão, ele se apoia em primitivas modernas de CSS scroll-snap em vez de uma pesada lógica de transformação em JS.
Como resultado, o deslizamento por toque, a rolagem por trackpad e a navegação por setas do teclado funcionam instantaneamente mesmo antes da hidratação do cliente. O JavaScript é sobreposto com elegância somente quando indicadores, botões anterior/próximo e gatilhos de reprodução automática são clicados.
Uso
Você pode configurar e ordenar os slides, definir layouts de exibição e controlar as propriedades de reprodução automática.
Apresentação básica
Um banner de imagens padrão com slides em largura total, legendas sobrepostas e links de navegação. Ideal para cabeçalhos hero ou vitrines na página principal.
{
"blockType": "carousel",
"slides": [
{
"image": "https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=800&q=80",
"caption": "Real-Time Analytics — Pulse delivers live data and dashboards with sub-second streaming latency.",
"href": "/features/analytics"
},
{
"image": "https://images.unsplash.com/photo-1518186285589-2f7649de83e0?w=800&q=80",
"caption": "AI-Powered Detection — Smart anomaly detection notifies your team before production breaks.",
"href": "/features/ai-detection"
},
{
"image": "https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=800&q=80",
"caption": "Unified Team Workspaces — Share annotated charts and build custom workspaces with ease.",
"href": "/features/workspaces"
}
]
}
Banner com autoplay e controles ao passar o cursor
Configure o carrossel para avançar automaticamente em uma velocidade definida. Para manter a interface acessível e discreta, ative pauseOnHover para que os usuários possam pausar a reprodução simplesmente passando o cursor sobre um slide.
{
"blockType": "carousel",
"loop": true,
"pauseOnHover": true,
"autoplayDelay": 3500,
"slides": [
{
"image": "https://images.unsplash.com/photo-1504384308090-c894fdcc538d?w=800&q=80",
"caption": "Developer Tools — Integrate your APIs in minutes with our native SDK wrappers.",
"href": "/developers"
},
{
"image": "https://images.unsplash.com/photo-1526374965328-7f61d4dc18c5?w=800&q=80",
"caption": "Ironclad Security — SOC2-compliant data storage and end-to-end encryption by default.",
"href": "/security"
}
]
}
Layout de múltiplos slides
Exiba vários slides lado a lado simultaneamente. Excelente para listas de produtos, diretórios de equipe e galerias de portfólio. Defina o atributo slidesPerPage junto com um spacing personalizado entre os itens.
{
"blockType": "carousel",
"slidesPerPage": 2,
"spacing": "16px",
"slides": [
{
"image": "https://images.unsplash.com/photo-1542744094-3a31f103e35f?w=400&q=80",
"caption": "Marketing Solutions",
"href": "/solutions/marketing"
},
{
"image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=400&q=80",
"caption": "Financial Growth",
"href": "/solutions/financial"
},
{
"image": "https://images.unsplash.com/photo-1551836022-d5d88e9218df?w=400&q=80",
"caption": "HR Management",
"href": "/solutions/hr"
},
{
"image": "https://images.unsplash.com/photo-1507679799987-c73779587ccf?w=400&q=80",
"caption": "Executive Advisory",
"href": "/solutions/consulting"
}
]
}
Feed de galeria vertical
Role pelo conteúdo dos seus slides verticalmente em vez de horizontalmente. Excelente para cartões de conteúdo mobile-first, bobinas de mídia ou painéis de navegação lateral.
{
"blockType": "carousel",
"orientation": "vertical",
"slides": [
{
"image": "https://images.unsplash.com/photo-1517841905240-472988babdf9?w=800&q=80",
"caption": "Curated Feed — Category Spotlight"
},
{
"image": "https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=800&q=80",
"caption": "Trending Creator Profile"
},
{
"image": "https://images.unsplash.com/photo-1506794778202-cad84cf45f1d?w=800&q=80",
"caption": "Featured Technical Portfolio"
}
]
}
Tema de destaque com controles sobrepostos
Faça com que os gatilhos anterior/próximo e os pontos flutuem diretamente sobre as imagens (em vez de colocá-los abaixo) usando a propriedade inline, e tinga os sinais visuais ativos com um token colorPalette de destaque.
{
"blockType": "carousel",
"inline": true,
"colorPalette": "purple",
"slides": [
{
"image": "https://images.unsplash.com/photo-1507238691740-187a5b1d37b8?w=800&q=80",
"caption": "Overlay Design Layout"
},
{
"image": "https://images.unsplash.com/photo-1531403009284-440f080d1e12?w=800&q=80",
"caption": "High Fidelity Previews"
}
]
}
Propriedades
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
slides | List | - | Uma coleção ordenada de slides individuais (ver esquema abaixo). |
slidesPerPage | Number | 1 | Quantidade de slides visíveis no viewport simultaneamente. |
spacing | String | - | Espaçamento compatível com CSS entre os slides visíveis (ex. "16px", "1rem"). |
loop | Boolean | false | Se o carrossel volta ao primeiro slide ao chegar ao final. |
autoplayDelay | Number | - | Temporizador de avanço automático em milissegundos. Deixe em branco ou omita para desativar o autoplay completamente. |
pauseOnHover | Boolean | true | Pausa a reprodução automática quando o ponteiro do usuário passa sobre os slides. |
orientation | Select | horizontal | Direção do layout de rolagem. Opções: horizontal, vertical. |
inline | Boolean | false | Sobrepõe os controles de navegação e os pontos sobre a mídia do slide em vez de colocá-los em um contêiner abaixo. |
colorPalette | Select | - | Cor de destaque visual para botões e indicadores. Opções: blue, green, red, purple, orange, amber, cyan, slate. |
Esquema do item de slide
Cada entrada no parâmetro slides aceita as seguintes propriedades:
| Propriedade | Tipo | Obrigatório | Descrição |
|---|---|---|---|
image | Image | Sim | Caminho ou URL da imagem de fundo do slide. |
caption | String | Não | Texto de descrição sobreposto renderizado dinamicamente na região inferior do slide. |
href | String | Não | URL de navegação ou rota de página localizada que o slide inteiro dispara ao clicar. |
Notas de arquitetura
- Zero mudanças de layout durante SSR: Para eliminar saltos de layout durante a renderização no servidor, os marcadores de ponto de ancoragem e as larguras do viewport são pré-calculados usando uma fórmula estrutural previsível que corresponde às configurações de
slideCounteslidesPerPage. - Delegação robusta de eventos: Todos os manipuladores de clique para indicadores, paginação por pontos e gatilhos de pausa são gerenciados por meio de um único listener de eventos unificado delegado a partir do contêiner raiz. Isso evita atribuir repetidamente listeners de eventos a componentes estáticos dentro do modelo de página hidratado.
- CSS Scroll Snap: O CSS scroll-snap puro trata do alinhamento de layout nativamente. Em telas touch móveis e trackpads modernos, as transições de deslizamento ao rolar permanecem suaves e funcionam corretamente mesmo quando o JavaScript está desativado ou atrasado.