in English

Carrossel

Um componente de apresentação de slides para percorrer elementos — imagens ou slides de texto — como um carrossel.

Como funciona

O carrossel é uma apresentação de slides para percorrer uma série de conteúdo, construída com transformações CSS 3D e um pouco de JavaScript. Ele funciona com uma série de imagens, texto ou marcação personalizada. Também inclui suporte para controles e indicadores anteriores/próximos.

Nos navegadores em que a API de visibilidade da página é compatível, o carrossel evitará o deslizamento quando a página da Web não estiver visível para o usuário (como quando a guia do navegador estiver inativa, a janela do navegador estiver minimizada etc.).

O efeito de animação deste componente depende da prefers-reduced-motionconsulta de mídia. Consulte a seção de movimento reduzido de nossa documentação de acessibilidade .

Esteja ciente de que os carrosséis aninhados não são suportados e os carrosséis geralmente não são compatíveis com os padrões de acessibilidade.

Por fim, se você estiver construindo nosso JavaScript a partir da fonte, ele requerutil.js .

Exemplo

Os carrosséis não normalizam automaticamente as dimensões do slide. Como tal, pode ser necessário usar utilitários adicionais ou estilos personalizados para dimensionar o conteúdo adequadamente. Embora os carrosséis suportem controles e indicadores anteriores/seguintes, eles não são explicitamente necessários. Adicione e personalize como achar melhor.

A .activeclasse precisa ser adicionada a um dos slides , caso contrário o carrossel não ficará visível. Certifique-se também de definir um exclusivo idpara .carouselcontroles opcionais, especialmente se estiver usando vários carrosséis em uma única página. Os elementos de controle e indicador devem ter um data-targetatributo (ou hrefpara links) que corresponda ao iddo .carouselelemento.

Somente slides

Aqui está um carrossel apenas com slides. Observe a presença de .d-blocke .w-100nas imagens do carrossel para evitar o alinhamento da imagem padrão do navegador.

<div id="carouselExampleSlidesOnly" class="carousel slide" data-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>

Com controles

Adicionando os controles anterior e seguinte. Recomendamos o uso <button>de elementos, mas você também pode usar <a>elementos com role="button".

<div id="carouselExampleControls" class="carousel slide" data-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-target="#carouselExampleControls" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleControls" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

Com indicadores

Você também pode adicionar os indicadores ao carrossel, juntamente com os 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 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-target="#carouselExampleIndicators" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleIndicators" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

Com legendas

Adicione legendas aos seus slides facilmente com o .carousel-captionelemento em qualquer arquivo .carousel-item. Eles podem ser facilmente ocultados em viewports menores, conforme mostrado abaixo, com utilitários de exibição opcionais . Nós os ocultamos inicialmente com .d-nonee os trazemos de volta em dispositivos de tamanho médio com .d-md-block.

<div id="carouselExampleCaptions" class="carousel slide" data-ride="carousel">
  <ol class="carousel-indicators">
    <li data-target="#carouselExampleCaptions" data-slide-to="0" class="active"></li>
    <li data-target="#carouselExampleCaptions" data-slide-to="1"></li>
    <li data-target="#carouselExampleCaptions" data-slide-to="2"></li>
  </ol>
  <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-target="#carouselExampleCaptions" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleCaptions" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

Crossfade

Adicione .carousel-fadeao seu carrossel para animar slides com uma transição de fade em vez de um slide. Dependendo do conteúdo do seu carrossel (por exemplo, slides somente texto), você pode querer adicionar .bg-bodyou algum CSS personalizado ao .carousel-items para um crossfading adequado.

<div id="carouselExampleFade" class="carousel slide carousel-fade" data-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-target="#carouselExampleFade" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleFade" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

Adicione data-interval=""a a .carousel-itempara alterar o tempo de atraso entre o ciclo automático para o próximo item.

<div id="carouselExampleInterval" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-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-target="#carouselExampleInterval" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleInterval" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

Desabilitar a passagem de toque

Os carrosséis suportam deslizar para a esquerda/direita em dispositivos com tela sensível ao toque para mover-se entre os slides. Isso pode ser desabilitado usando o data-touchatributo. O exemplo abaixo também não inclui o data-rideatributo e tem data-interval="false"para que ele não seja reproduzido automaticamente.

<div id="carouselExampleControlsNoTouching" class="carousel slide" data-touch="false" data-interval="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-target="#carouselExampleControlsNoTouching" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-target="#carouselExampleControlsNoTouching" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </button>
</div>

Uso

Por atributos de dados

Use atributos de dados para controlar facilmente a posição do carrossel. data-slideaceita as palavras-chave prevou next, que altera a posição do slide em relação à sua posição atual. Como alternativa, use data-slide-topara passar um índice de slide bruto para o carrossel data-slide-to="2", que muda a posição do slide para um índice específico começando com 0.

O data-ride="carousel"atributo é usado para marcar um carrossel como animado a partir do carregamento da página. Se você não usa data-ride="carousel"para inicializar seu carrossel, você mesmo deve inicializá-lo. Ele não pode ser usado em combinação com a inicialização JavaScript explícita (redundante e desnecessária) do mesmo carrossel.

Por JavaScript

Chame o carrossel manualmente com:

$('.carousel').carousel()

Opções

As opções podem ser passadas por meio de atributos de dados ou JavaScript. Para atributos de dados, anexe o nome da opção a data-, como em data-interval="".

Nome Modelo Predefinição Descrição
intervalo número 5000 A quantidade de tempo de atraso entre o ciclo automático de um item. Se false, o carrossel não irá ciclar automaticamente.
teclado boleano verdadeiro Se o carrossel deve reagir a eventos de teclado.
pausa seqüência | boleano 'flutuar'

Se definido como 'hover', pausa o ciclo do carrossel ligado mouseentere retoma o ciclo do carrossel ligado mouseleave. Se definido como false, passar o mouse sobre o carrossel não o pausará.

Em dispositivos habilitados para toque, quando definido como 'hover', o ciclismo fará uma pausa touchend(quando o usuário terminar de interagir com o carrossel) por dois intervalos, antes de retomar automaticamente. Observe que isso é um acréscimo ao comportamento do mouse acima.
passeio corda falso Reproduz automaticamente o carrossel depois que o usuário alterna manualmente o primeiro item. Se definido como 'carousel', reproduz automaticamente o carrossel ao carregar.
enrolar boleano verdadeiro Se o carrossel deve circular continuamente ou ter paradas bruscas.
toque boleano verdadeiro Se o carrossel deve suportar interações de deslizamento para a esquerda/direita em dispositivos com tela sensível ao toque.

Métodos

Métodos e transições assíncronas

Todos os métodos de API são assíncronos e iniciam uma transição . Eles retornam ao chamador assim que a transição é iniciada, mas antes que ela termine . Além disso, uma chamada de método em um componente de transição será ignorada .

Consulte nossa documentação JavaScript para obter mais informações .

.carousel(options)

Inicializa o carrossel com opções opcionais objecte começa a percorrer os itens.

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

.carousel('cycle')

Percorre os itens do carrossel da esquerda para a direita.

.carousel('pause')

Interrompe o carrossel de percorrer os itens.

.carousel(number)

Alterna o carrossel para um quadro específico (baseado em 0, semelhante a uma matriz). Retorna ao chamador antes que o item de destino seja mostrado (ou seja, antes que o slid.bs.carouselevento ocorra).

.carousel('prev')

Volta ao item anterior. Retorna ao chamador antes que o item anterior tenha sido mostrado (ou seja, antes que o slid.bs.carouselevento ocorra).

.carousel('next')

Alterna para o próximo item. Retorna ao chamador antes que o próximo item seja mostrado (ou seja, antes que o slid.bs.carouselevento ocorra).

.carousel('dispose')

Destrói o carrossel de um elemento.

.carousel('nextWhenVisible')

Não alterne o carrossel para o próximo quando a página não estiver visível ou o carrossel ou seu pai não estiver visível. Retorna ao chamador antes que o próximo item seja mostrado (ou seja, antes que o slid.bs.carouselevento ocorra).

.carousel('to')

Alterna o carrossel para um quadro específico (baseado em 0, semelhante a uma matriz). Retorna ao chamador antes que o próximo item seja mostrado (ou seja, antes que o slid.bs.carouselevento ocorra).

Eventos

A classe carrossel do Bootstrap expõe dois eventos para conectar-se à funcionalidade do carrossel. Ambos os eventos têm as seguintes propriedades adicionais:

  • direction: A direção na qual o carrossel está deslizando (ou "left"ou "right").
  • relatedTarget: o elemento DOM que está sendo posicionado como o item ativo.
  • from: O índice do item atual
  • to: O índice do próximo item

Todos os eventos de carrossel são disparados no próprio carrossel (ou seja, no <div class="carousel">).

Tipo de evento Descrição
slide.bs.carrossel Esse evento é acionado imediatamente quando o slidemétodo de instância é invocado.
slide.bs.carrossel Este evento é acionado quando o carrossel conclui sua transição de slides. 
$('#myCarousel').on('slide.bs.carousel', function () {
  // do something...
})

Alterar duração da transição

A duração da transição .carousel-itempode ser alterada com a $carousel-transitionvariável Sass antes de compilar ou estilos personalizados se você estiver usando o CSS compilado. Se várias transições forem aplicadas, certifique-se de que a transição de transformação seja definida primeiro (por exemplo transition: transform 2s ease, opacity .5s ease-out, ).