Carousel Carrusel
Introducción
El componente Carousel es una presentación de diapositivas de alto rendimiento que se desplaza de forma nativa y avanza página por página a través de un conjunto de slides. Creado específicamente para la construcción de páginas en el CMS y con renderizado estático sin JS por defecto, se apoya en primitivas modernas de CSS scroll-snap en lugar de una pesada lógica de transformación en JS.
Como resultado, el deslizamiento táctil, el desplazamiento con trackpad y la navegación con las teclas de flecha del teclado funcionan al instante incluso antes de la hidratación del cliente. JavaScript se superpone con elegancia solo cuando se hace clic en los indicadores, los botones de anterior/siguiente y los disparadores de reproducción automática.
Uso
Puedes configurar y ordenar los slides, definir los layouts de visualización y controlar las propiedades de reproducción automática.
Presentación básica
Un banner de imágenes estándar con slides a todo ancho, texto superpuesto y enlaces de navegación. Ideal para encabezados hero o muestras en la 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 con autoplay y controles al pasar el cursor
Configura el carrusel para avanzar automáticamente a una velocidad determinada. Para mantener la interfaz accesible y discreta, activa pauseOnHover para que los usuarios puedan pausar la reproducción simplemente pasando el cursor sobre un 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"
}
]
}
Diseño de varios slides
Muestra varios slides uno al lado del otro simultáneamente. Excelente para listas de productos, directorios de equipo y galerías de portafolio. Define el atributo slidesPerPage junto con un spacing personalizado entre los elementos.
{
"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 galería vertical
Desplázate por el contenido de tus slides en vertical en lugar de horizontal. Excelente para tarjetas de contenido mobile-first, carretes multimedia o paneles de navegación 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 acento con controles superpuestos
Haz que los disparadores de anterior/siguiente y los puntos floten directamente sobre las imágenes (en lugar de colocarlos debajo) mediante la propiedad inline, y tiñe las señales visuales activas con un token de colorPalette con acento.
{
"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"
}
]
}
Propiedades
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
slides | List | - | Una colección ordenada de slides individuales (ver esquema abajo). |
slidesPerPage | Number | 1 | Cantidad de slides visibles en el viewport simultáneamente. |
spacing | String | - | Espacio/separación compatible con CSS entre los slides visibles (p. ej., "16px", "1rem"). |
loop | Boolean | false | Si el carrusel vuelve al primer slide al llegar al final. |
autoplayDelay | Number | - | Temporizador de avance automático en milisegundos. Déjalo en blanco u omítelo para desactivar el autoplay por completo. |
pauseOnHover | Boolean | true | Pausa el autoplay cuando el puntero del usuario se sitúa sobre los slides. |
orientation | Select | horizontal | Dirección del layout de desplazamiento. Opciones: horizontal, vertical. |
inline | Boolean | false | Superpone los controles de navegación y los puntos sobre el medio del slide en lugar de colocarlos en un contenedor inferior. |
colorPalette | Select | - | Color de acento visual para botones e indicadores. Opciones: blue, green, red, purple, orange, amber, cyan, slate. |
Esquema del elemento slide
Cada entrada del parámetro slides acepta las siguientes propiedades:
| Propiedad | Tipo | Requerido | Descripción |
|---|---|---|---|
image | Image | Sí | Ruta o URL de la imagen de fondo del slide. |
caption | String | No | Texto de descripción superpuesto que se renderiza dinámicamente en la parte inferior del slide. |
href | String | No | URL de navegación o ruta de página localizada que el slide completo dispara al hacer clic. |
Notas de arquitectura
- Cero cambios de diseño durante SSR: Para eliminar los saltos de diseño durante el renderizado en el servidor, los marcadores de punto de anclaje y los anchos del viewport se precalculan mediante una fórmula estructural predecible que coincide con la configuración de
slideCountyslidesPerPage. - Delegación robusta de eventos: Todos los manejadores de clic para indicadores, paginación de puntos y disparadores de pausa se gestionan mediante un único listener de eventos unificado delegado desde el contenedor raíz. Esto evita asignar repetidamente listeners de eventos a componentes estáticos dentro de la plantilla de página hidratada.
- CSS Scroll Snap: El CSS scroll-snap puro maneja la alineación del diseño de forma nativa. En pantallas táctiles móviles y trackpads modernos, las transiciones de deslizamiento al desplazar permanecen suaves y funcionan correctamente incluso cuando JavaScript está desactivado o retrasado.