Carousel

Um componente de slideshow para fazer um giro através de elementos (imagens ou slides de texto), como se fosse um carrosel.

Como funciona

O carousel é um slideshow para fazer um giro em vários coteúdos, construído com CSS 3D transforms e um pouco de JavaScript. Ele funciona com o uso de imagens, texto ou marcação personalizada. Também possui suporte para controles anterior, próximo e indicadores.

Nos navegadores onde a API Page Visibility é suportada, o carousel vai evitar deslizar quando a página não está visível para o usuário (como quando o browser está inativo, janela minimizada, etc).

Por favor, esteja atento que carousels aninhados não são suportados e não são, geralmente, amigáveis aos padrões de acessibilidades.

Por último, se você está construindo nosso JavaScript a partir da fonte, vai precisar do util.js.

Exemplo

Carousels não normalizam dimensões, automaticamente. Assim, você pode precisar usar utilitários adicionais ou estilos personalizados para dimensionar conteúdos, apropriadamente. Apesar de carousels suportarem controles anterior, próximo e indicadores, eles não são obrigatórios, necessariamente. Use e abuse, como quiser.

A classe .active precisa ser usada em um dos slides, caso contrário, o carousel não ficará visível. Também, se assegure de definir um único ID no .carousel para os controles opcionais, especialmente, se você está usando múltiplos carousels em uma página. Elementos de controle e indicador devem ter um atributo data-target (ou links href) que combinam com o ID do elemento .carousel.

Só slides

Aqui está um carousel só com slides. Perceba a presença do .d-block e .w-100 nas imagens do carousel para evitar alinhamento padrão de imagens do navegador.

<div id="carouselExampleSlidesOnly" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=777&fg=555&text=Primeiro Slide" alt="Primeiro Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=666&fg=444&text=Segundo Slide" alt="Segundo Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=555&fg=333&text=Terceiro Slide" alt="Terceiro Slide">
    </div>
  </div>
</div>

Com controles

Adicionando os controles anterior e próximo, temos isso:

<div id="carouselExampleControls" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=777&fg=555&text=Primeiro Slide" alt="Primeiro Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=666&fg=444&text=Segundo Slide" alt="Segundo Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=555&fg=333&text=Terceiro Slide" alt="Terceiro Slide">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleControls" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Anterior</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleControls" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Próximo</span>
  </a>
</div>

Com indicadores

Você também pode adicionar indicadores ao carousel, além dos controles.

<div id="carouselExampleIndicators" class="carousel slide" data-ride="carousel">
  <ol class="carousel-indicators">
    <li data-target="#carouselExampleIndicators" data-slide-to="0" class="active"></li>
    <li data-target="#carouselExampleIndicators" data-slide-to="1"></li>
    <li data-target="#carouselExampleIndicators" data-slide-to="2"></li>
  </ol>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=777&fg=555&text=Primeiro Slide" alt="Primeiro Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=666&fg=444&text=Segundo Slide" alt="Segundo Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=555&fg=333&text=Terceiro Slide" alt="Terceiro Slide">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleIndicators" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Anterior</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleIndicators" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Próximo</span>
  </a>
</div>

Com legenda

Adicione legendas nos seus slides, facilmente, usando o elemento .carousel-caption dentro de qualquer .carousel-item. Eles podem ser escondidos, facilmente, em qualquer viewport menor, como mostrado é mostrado abaixo, usando utilitários display. Escondemos eles, inicialmente, com .d-none e trazemos de volta em dispositivos de tamanho mediano, usando .d-md-block.

Título do primeiro slide

Nulla vitae elit libero, a pharetra augue mollis interdum.

Título do segundo slide

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Título do terceiro slide

Praesent commodo cursus magna, vel scelerisque nisl consectetur.

<div class="carousel-item">
  <img src="..." alt="...">
  <div class="carousel-caption d-none d-md-block">
    <h5>...</h5>
    <p>...</p>
  </div>
</div>

Crossfade

Use .carousel-fade no seu carousel para animar os slides com uma transição esmaecida, invés de um simples slide.

<div id="carouselExampleFade" class="carousel slide carousel-fade" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=777&fg=555&text=Primeiro Slide" alt="Primeiro Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=666&fg=444&text=Segundo Slide" alt="Segundo Slide">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src=".../800x400?auto=yes&bg=555&fg=333&text=Terceiro Slide" alt="Terceiro Slide">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleFade" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Anterior</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleFade" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Próximo</span>
  </a>
</div>

Modo de uso

Via atributos data

Use atributos data para, facilmente, controlar a posição do carousel. O data-slide aceita as palavras-chaves prev ou next, as quais alteram a posição do slide, de acordo com sua atual posição. Opcionalmente, use data-slide-to para passar um index ao carousel, o qual muda a posição do slide para o index específico, com valores começando em 0 (ex: data-slide-to="2").

O atributo data-ride="carousel" é usado para declarar que o carousel vai começar a animação assim que a página carregar. Este atributo não pode ser usado em combinação com uma (redundante e desnecessária) inicialização JavaScript explícita, do mesmo carousel.

Via JavaScript

Invoque o carousel, manualmente, usando:

$('.carousel').carousel()

Opções

Opções podem ser passadas via atributos data ou JavaScript. Para atributos data, anexe o nome da opção no prefixo data-, como acontece em data-interval="".

Nome	Tipo	Padrão	Descrição
interval	number	5000	A quantidade de tempo de espera entre a troca de slides. Se o valor é false, o carousel não vai girar, automaticamente.
keyboard	booleano	true	Diz se o carousel deve reagir aos eventos de teclado.
pause	string \| booleano	"hover"	Se tiver definido como `"hover"`, pausa o ciclo do carousel no evento `mouseenter` e volta o ciclo no `mouseleave`. Se definido para `false`, passar o mouse sobre o carousel não irá pausá-lo. Em dispositivos com touch, quando tiver definido o valor `"hover"`, o ciclo vai pausar no evento `touchend` (uma vez que o usuário parar de interagir com o carousel) por dois intervalos, antes de voltar sozinho, novamente. Perceba que isso acontece devido ao comportamento de mouse, mencionado acima.
ride	string	false	Auto inicia o carousel, depois do usuário clicar no primeiro item, manualmente. Se definido com o valor "carousel", o carousel começa assim que carrega.
wrap	boolean	true	Diz se o carousel deve girar continuamente ou ter paradas bruscas.

Métodos

Métodos é transições assíncronas

Todos métodos API são assíncronos e iniciam a transição. Eles retornam ao invocador, assim que a transição é iniciada, mas que ela finalize. Além do mais, uma chamada de método em um componente transicionando é ignorada.

Veja nossa documentação JavaScript, para mais informação.

`.carousel(options)`

Inicializa o carousel com um object de opções opcional e inicia o ciclo dos itens.

$('.carousel').carousel({
  interval: 2000
})

`.carousel('cycle')`

Gira pelos itens do carousel, da esquerda para direita.

`.carousel('pause')`

Impede o carousel de girar pelos itens.

`.carousel(Número)`

Gira o carousel para um frame particular (começa em 0, como uma array). Retorna ao invocador, antes do item alvo ser mostrado (antes do evento slid.bs.carousel ocorrer).

`.carousel('prev')`

Gira para o item anterior. Retorna ao invocador, antes do item anterior ser mostrado (antes do evento slid.bs.carousel ocorrer).

`.carousel('next')`

Gira para o próximo item. Retorna ao invocador, antes do próximo item ser mostrado (antes do evento slid.bs.carousel ocorrer).

`.carousel('dispose')`

Destroi um elemento do carousel.

Eventos

A classe carousel do Bootstrap tem dois evento para serem ligados a funcionalidade do carousel. Ambos eventos possuem as seguintes propriedades adicionais:

direction: a direção na qual o carousel está deslizando (tanto "left" quanto "right");
relatedTarget: o elemento DOM que está sendo deslizado para o lugar do item ativo;
from: o index do atual item;
to: o index do próximo item.

Todos eventos carousel são acionados no próprio carousel (acionados no elemento <div class="carousel">).

Tipo de evento	Descrição
slide.bs.carousel	Este evento aciona, imediatamente, quando o método `slide` é invocado.
slid.bs.carousel	Este evento é acionado quando o carousel acabou de finalizar sua transição.

$('#myCarousel').on('slide.bs.carousel', function () {
  // Faça algo...
})

Mude a duração da transição

A duração da transição do .carousel-item pode ser alterada na variável Sass $carousel-transition, antes de compilar ou em estilos personalizados (se você está usando CSS compilado). Se várias transições são aplicadas, se assegure da transição transform ser declarada primeiro (ex: transition: transform 2s ease, opacity .5s ease-out).