Ir ao contido principal Ir á navegación de documentos
Check
in English

Carrusel

Un compoñente de presentación de diapositivas para percorrer elementos (imaxes ou diapositivas de texto) como un carrusel.

Nesta páxina

Cómo funciona

O carrusel é unha presentación de diapositivas para percorrer unha serie de contidos, construído con transformacións CSS 3D e un pouco de JavaScript. Funciona cunha serie de imaxes, texto ou marcas personalizadas. Tamén inclúe soporte para controis e indicadores anteriores/seguintes.

Nos navegadores nos que se admite a API de visibilidade da páxina , o carrusel evitará deslizarse cando a páxina web non sexa visible para o usuario (por exemplo, cando a pestana do navegador está inactiva, a xanela do navegador está minimizada, etc.).

O efecto de animación deste compoñente depende da prefers-reduced-motionconsulta multimedia. Consulta a sección de movemento reducido da nosa documentación de accesibilidade .

Teña en conta que os carrusels anidados non son compatibles e que, en xeral, os carruseles non cumpren os estándares de accesibilidade.

Exemplo

Os carrusels non normalizan automaticamente as dimensións das diapositivas. Polo tanto, é posible que necesites usar utilidades adicionais ou estilos personalizados para dimensionar adecuadamente o contido. Aínda que os carrusels admiten controis e indicadores anteriores ou seguintes, non son necesarios de forma explícita. Engade e personaliza como creas oportuno.

A .activeclase debe engadirse a unha das diapositivas , se non, o carrusel non estará visible. Tamén asegúrate de configurar un único para idos .carouselcontrois opcionais, especialmente se estás a usar varios carruseles nunha mesma páxina. Os elementos de control e indicador deben ter un data-bs-targetatributo (ou hrefpara as ligazóns) que coincida co iddo .carouselelemento.

Só diapositivas

Aquí tes un carrusel só con diapositivas. Teña en conta a presenza de .d-blocke .w-100nas imaxes do carrusel para evitar o aliñamento de imaxes predeterminado do navegador.

html 
<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
</div>

Con controis

Engadindo os controis anteriores e seguintes. Recomendamos usar <button>elementos, pero tamén pode usar <a>elementos con role="button".

html 
<div id="carouselExampleControls" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Con indicadores

Tamén podes engadir os indicadores ao carrusel, xunto cos controis.

html 
<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Con subtítulos

Engade subtítulos ás túas diapositivas facilmente co .carousel-captionelemento de calquera .carousel-item. Pódense ocultar facilmente en xanelas máis pequenas, como se mostra a continuación, con utilidades de visualización opcionais . Ocultámolos inicialmente con .d-nonee traémolos de volta en dispositivos de tamaño medio con .d-md-block.

html 
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Fundido cruzado

Engade .carousel-fadeao teu carrusel para animar as diapositivas cunha transición de fundido en lugar dunha diapositiva. Dependendo do contido do teu carrusel (por exemplo, diapositivas só de texto), quizais queiras engadir .bg-bodyou algún CSS personalizado ao .carousel-items para un fundido cruzado adecuado.

html 
<div id="carouselExampleFade" class="carousel slide carousel-fade" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Engadir data-bs-interval=""a a .carousel-itempara cambiar a cantidade de tempo que transcorre entre o paso automático ao seguinte elemento.

html 
<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Desactiva o dedo táctil

Os carrusels admiten pasar o dedo cara á esquerda/dereita nos dispositivos con pantalla táctil para moverse entre as diapositivas. Isto pódese desactivar usando o data-bs-touchatributo. O exemplo seguinte tampouco inclúe o data-bs-rideatributo polo que non se reproduce automaticamente.

html 
<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Variante escura

Engade .carousel-darka .carouselpara obter controis, indicadores e subtítulos máis escuros. Os controis invertéronse do seu recheo branco predeterminado coa filterpropiedade CSS. Os subtítulos e os controis teñen variables Sass adicionais que personalizan o colore background-color.

html 
<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Transición personalizada

A duración da transición de .carousel-itempódese cambiar coa $carousel-transition-durationvariable Sass antes de compilar ou estilos personalizados se estás a usar o CSS compilado. Se se aplican varias transicións, asegúrate de que a transición de transformación estea definida primeiro (por exemplo transition: transform 2s ease, opacity .5s ease-out, ).

Sass

Variables

Variables para todos os carrusel:

$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;

$carousel-indicator-width:           30px;
$carousel-indicator-height:          3px;
$carousel-indicator-hit-area-height: 10px;
$carousel-indicator-spacer:          3px;
$carousel-indicator-opacity:         .5;
$carousel-indicator-active-bg:       $white;
$carousel-indicator-active-opacity:  1;
$carousel-indicator-transition:      opacity .6s ease;

$carousel-caption-width:             70%;
$carousel-caption-color:             $white;
$carousel-caption-padding-y:         1.25rem;
$carousel-caption-spacer:            1.25rem;

$carousel-control-icon-width:        2rem;

$carousel-control-prev-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/></svg>");
$carousel-control-next-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/></svg>");

$carousel-transition-duration:       .6s;
$carousel-transition:                transform $carousel-transition-duration ease-in-out; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`)

Variables para o carrusel escuro :

$carousel-dark-indicator-active-bg:  $black;
$carousel-dark-caption-color:        $black;
$carousel-dark-control-icon-filter:  invert(1) grayscale(100);

Uso

A través de atributos de datos

Usa atributos de datos para controlar facilmente a posición do carrusel. data-bs-slideacepta as palabras clave prevou next, que altera a posición da diapositiva en relación coa súa posición actual. Alternativamente, úsao data-bs-slide-topara pasar un índice de diapositivas en bruto ao carrusel data-bs-slide-to="2", que cambia a posición da diapositiva a un índice concreto que comeza por 0.

O data-bs-ride="carousel"atributo úsase para marcar un carrusel como animación a partir da carga da páxina. Se non o utilizas data-bs-ride="carousel"para inicializar o teu carrusel, tes que inicializalo ti mesmo. Non se pode usar en combinación coa inicialización explícita de JavaScript (redundante e innecesaria) do mesmo carrusel.

Vía JavaScript

Chamar ao carrusel manualmente con:

const carousel = new bootstrap.Carousel('#myCarousel')

Opcións

Como as opcións se poden pasar a través de atributos de datos ou JavaScript, pode engadir un nome de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar o tipo de maiúsculas e minúsculas do nome da opción de " camelCase " a " kebab-case " ao pasar as opcións a través dos atributos de datos. Por exemplo, use data-bs-custom-class="beautifier"no canto de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos os compoñentes admiten un atributo de datos reservados experimentaisdata-bs-config que pode albergar unha configuración sinxela de compoñentes como cadea JSON. Cando un elemento ten data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"atributos, o titlevalor final será 456e os atributos de datos separados anularán os valores indicados en data-bs-config. Ademais, os atributos de datos existentes poden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Nome Tipo Por defecto Descrición
interval número 5000 A cantidade de tempo que transcorre entre o ciclo automático dun elemento.
keyboard booleano true Indica se o carrusel debe reaccionar aos eventos do teclado.
pause cadea, booleano "hover" Se se establece en "hover", detén o ciclo do carrusel activado mouseentere retoma o ciclo do carrusel activado mouseleave. Se se define como false, pasar o rato sobre o carrusel non o deterá. Nos dispositivos táctiles, cando se configura como "hover", o ciclo activarase touchend(unha vez que o usuario remate de interactuar co carrusel) durante dous intervalos, antes de retomarse automaticamente. Isto é ademais do comportamento do rato.
ride cadea, booleano false Se se define como true, reproduce automaticamente o carrusel despois de que o usuario faga un ciclo manualmente o primeiro elemento. Se se define como "carousel", reproduce automaticamente o carrusel ao cargar.
touch booleano true Indica se o carrusel debería admitir interaccións de desprazamento cara á esquerda/dereita nos dispositivos con pantalla táctil.
wrap booleano true Se o carrusel debe circular de forma continua ou ter paradas duras.

Métodos

Métodos asíncronos e transicións

Todos os métodos da API son asíncronos e inician unha transición . Volven ao interlocutor en canto se inicia a transición pero antes de que remate . Ademais, ignorarase unha chamada de método nun compoñente en transición .

Consulte a nosa documentación de JavaScript para obter máis información .

Podes crear unha instancia de carrusel co construtor de carrusel, por exemplo, para inicializar con opcións adicionais e comezar a percorrer os elementos:

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: false
})
Método Descrición
cycle Percorre os elementos do carrusel de esquerda a dereita.
dispose Destrúe o carrusel dun elemento. (Elimina os datos almacenados no elemento DOM)
getInstance Método estático que che permite obter a instancia do carrusel asociada a un elemento DOM, podes usalo así: bootstrap.Carousel.getInstance(element).
getOrCreateInstance Método estático que devolve unha instancia de carrusel asociada a un elemento DOM ou crea unha nova no caso de que non se inicializou. Podes usalo así: bootstrap.Carousel.getOrCreateInstance(element).
next Ciclos ao seguinte elemento. Volve ao interlocutor antes de que se amose o seguinte elemento (por exemplo, antes de slid.bs.carouselque se produza o evento).
nextWhenVisible Non pases do carrusel ao seguinte cando a páxina non estea visible ou o carrusel ou o seu pai non estean visibles. Volve ao interlocutor antes de que se mostrase o elemento de destino .
pause Evita que o carrusel pase por elementos.
prev Ciclos ao elemento anterior. Volve ao interlocutor antes de que se mostrase o elemento anterior (por exemplo, antes de slid.bs.carouselque se produza o evento).
to Cicla o carrusel a un cadro particular (baseado en 0, semellante a unha matriz). Volve ao interlocutor antes de que se mostrase o elemento de destino (por exemplo, antes de slid.bs.carouselque ocorra o evento).

Eventos

A clase de carrusel de Bootstrap expón dous eventos para conectarse á funcionalidade do carrusel. Ambos eventos teñen as seguintes propiedades adicionais:

  • direction: A dirección na que se despraza o carrusel ( "left"ou ben "right").
  • relatedTarget: o elemento DOM que se está a colocar como elemento activo.
  • from: O índice do elemento actual
  • to: O índice do seguinte elemento

Todos os eventos do carrusel desenvólvense no propio carrusel (é dicir, no <div class="carousel">).

Tipo de evento Descrición
slid.bs.carousel Despediuse cando o carrusel completou a súa transición de diapositivas.
slide.bs.carousel Dispara inmediatamente cando slidese invoca o método de instancia. 
const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // do something...
})