Ir para o conteúdo principal Pular para a navegação de documentos
in English

Carrossel

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

Nesta página

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.

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-bs-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-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>

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-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>

Com indicadores

Você também pode adicionar os indicadores ao carrossel, juntamente com os controles.

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

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-bs-ride="carousel">
  <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>

Crossfade

Adicione .carousel-fadeao seu carrossel para animar slides com uma transição de fade em vez de um slide.

<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>

Adicione data-bs-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-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>

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-bs-touchatributo. O exemplo abaixo também não inclui o data-bs-rideatributo e tem data-bs-interval="false"para que ele não seja reproduzido automaticamente.

<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false" data-bs-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-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

Adicione .carousel-darkao .carouselpara controles, indicadores e legendas mais escuros. Os controles foram invertidos de seu preenchimento branco padrão com a filterpropriedade CSS. As legendas e os controles têm variáveis ​​Sass adicionais que personalizam os arquivos colore background-color.

<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>

Transição personalizada

A duração da transição .carousel-itempode ser alterada com a $carousel-transition-durationvariá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, ).

Sass

Variáveis

$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`)

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

Uso

Por atributos de dados

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

O data-bs-ride="carousel"atributo é usado para marcar um carrossel como animado a partir do carregamento da página. Se você não usa data-bs-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:

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel)

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-bs-, como em data-bs-interval="".

Nome Modelo Predefinição Descrição
interval 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.
keyboard boleano true Se o carrossel deve reagir a eventos de teclado.
pause seqüência | boleano 'hover'

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.
ride seqüência | boleano false Reproduz automaticamente o carrossel depois que o usuário alterna manualmente o primeiro item. Se definido como 'carousel', reproduz automaticamente o carrossel ao carregar.
wrap boleano true Se o carrossel deve circular continuamente ou ter paradas bruscas.
touch boleano true 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 .

Você pode criar uma instância de carrossel com o construtor de carrossel, por exemplo, para inicializar com opções adicionais e começar a percorrer os itens:

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel, {
  interval: 2000,
  wrap: false
})
Método Descrição
cycle Percorre os itens do carrossel da esquerda para a direita.
pause Interrompe o carrossel de percorrer os itens.
prev Volta ao item anterior. Retorna ao chamador antes que o item anterior tenha sido mostrado (por exemplo, antes que o slid.bs.carouselevento ocorra).
next Alterna para o próximo item. Retorna ao chamador antes que o próximo item seja mostrado (por exemplo, antes que o slid.bs.carouselevento ocorra).
nextWhenVisible Não mude 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 item de destino seja mostrado
to 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 (por exemplo, antes que o slid.bs.carouselevento ocorra).
dispose Destrói o carrossel de um elemento. (Remove os dados armazenados no elemento DOM)
getInstance Método estático que permite obter a instância do carrossel associada a um elemento DOM, você pode usá-lo assim:bootstrap.Carousel.getInstance(element)
getOrCreateInstance Método estático que retorna uma instância de carrossel associada a um elemento DOM ou cria uma nova caso não tenha sido inicializada. Você pode usar assim:bootstrap.Carousel.getOrCreateInstance(element)

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.carousel Dispara imediatamente quando o slidemétodo de instância é invocado.
slid.bs.carousel Acionado quando o carrossel conclui sua transição de slides. 
var myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', function () {
  // do something...
})