Salta al contenuto principale Passa alla navigazione dei documenti
Check
in English

Giostra

Un componente di presentazione per scorrere gli elementi, immagini o diapositive di testo, come un carosello.

Su questa pagina

Come funziona

Il carosello è una presentazione per scorrere una serie di contenuti, costruiti con trasformazioni 3D CSS e un po' di JavaScript. Funziona con una serie di immagini, testo o markup personalizzato. Include anche il supporto per i controlli e gli indicatori precedenti/successivi.

Nei browser in cui è supportata l' API di visibilità della pagina , il carosello eviterà lo scorrimento quando la pagina Web non è visibile all'utente (ad esempio quando la scheda del browser è inattiva, la finestra del browser è ridotta a icona, ecc.).

L'effetto di animazione di questo componente dipende dalla prefers-reduced-motionmedia query. Vedi la sezione movimento ridotto della nostra documentazione sull'accessibilità .

Tieni presente che i caroselli nidificati non sono supportati e generalmente i caroselli non sono conformi agli standard di accessibilità.

Esempio

I caroselli non normalizzano automaticamente le dimensioni delle diapositive. Pertanto, potrebbe essere necessario utilizzare utilità aggiuntive o stili personalizzati per ridimensionare il contenuto in modo appropriato. Sebbene i caroselli supportino i controlli e gli indicatori precedenti/successivi, non sono esplicitamente richiesti. Aggiungi e personalizza come meglio credi.

La .activeclasse deve essere aggiunta a una delle diapositive, altrimenti il ​​carosello non sarà visibile. Assicurati anche di impostare un unico idper i .carouselcontrolli opzionali, soprattutto se stai utilizzando più caroselli su una singola pagina. Gli elementi di controllo e indicatore devono avere un data-bs-targetattributo (o hrefper i collegamenti) che corrisponda ida quello .carouseldell'elemento.

Solo diapositive

Ecco un carosello solo con diapositive. Notare la presenza di .d-blocke .w-100sulle immagini del carosello per impedire l'allineamento dell'immagine predefinito del browser.

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 controlli

Aggiunta dei controlli precedente e successivo. Ti consigliamo di utilizzare <button>gli elementi, ma puoi anche utilizzare <a>gli elementi 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 indicatori

Puoi anche aggiungere gli indicatori al carosello, insieme ai controlli.

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 didascalie

Aggiungi facilmente didascalie alle tue diapositive con l' .carousel-captionelemento all'interno di qualsiasi .carousel-item. Possono essere facilmente nascosti su finestre più piccole, come mostrato di seguito, con utilità di visualizzazione opzionali . Inizialmente li nascondiamo con .d-nonee li riportiamo su dispositivi di medie dimensioni 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>

Dissolvenza incrociata

Aggiungi .carousel-fadeal tuo carosello per animare le diapositive con una transizione di dissolvenza invece di una diapositiva. A seconda del contenuto del tuo carosello (ad esempio, diapositive di solo testo), potresti voler aggiungere .bg-bodyo alcuni CSS personalizzati alle .carousel-items per una corretta dissolvenza incrociata.

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>

Aggiungi data-bs-interval=""a .carousel-itemper modificare la quantità di tempo di ritardo tra il passaggio automatico all'elemento successivo.

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>

Disabilita lo scorrimento del tocco

I caroselli supportano lo scorrimento a sinistra/destra sui dispositivi touchscreen per spostarsi tra le diapositive. Questo può essere disabilitato usando l' data-bs-touchattributo. Anche l'esempio seguente non include l' data-bs-rideattributo, quindi non viene riprodotto 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 scura

Aggiungi .carousel-darka .carouselper controlli, indicatori e didascalie più scuri. I controlli sono stati invertiti dal riempimento bianco predefinito con la filterproprietà CSS. Didascalie e controlli hanno variabili Sass aggiuntive che personalizzano il file 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>

Transizione personalizzata

La durata della transizione di .carousel-itempuò essere modificata con la $carousel-transition-durationvariabile Sass prima della compilazione o stili personalizzati se stai usando il CSS compilato. Se vengono applicate più transizioni, assicurarsi che la transizione di trasformazione sia prima definita (ad es transition: transform 2s ease, opacity .5s ease-out. ).

Sass

Variabili

Variabili per tutti i caroselli:

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

Variabili per il carosello scuro :

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

Utilizzo

Tramite attributi di dati

Usa gli attributi dei dati per controllare facilmente la posizione del carosello. data-bs-slideaccetta le parole chiave prevo next, che altera la posizione della diapositiva rispetto alla sua posizione corrente. In alternativa, utilizzare data-bs-slide-toper passare un indice di diapositiva non elaborato al carosello data-bs-slide-to="2", che sposta la posizione della diapositiva su un indice particolare che inizia con 0.

L' data-bs-ride="carousel"attributo viene utilizzato per contrassegnare un carosello come animato a partire dal caricamento della pagina. Se non lo usi data-bs-ride="carousel"per inizializzare il tuo carosello, devi inizializzarlo tu stesso. Non può essere utilizzato in combinazione con l'inizializzazione JavaScript esplicita (ridondante e non necessaria) dello stesso carosello.

Tramite JavaScript

Chiama il carosello manualmente con:

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

Opzioni

Poiché le opzioni possono essere passate tramite attributi di dati o JavaScript, puoi aggiungere un nome di opzione a data-bs-, come in data-bs-animation="{value}". Assicurati di cambiare il tipo di caso del nome dell'opzione da " camelCase " a " kebab-case " quando passi le opzioni tramite attributi di dati. Ad esempio, utilizzare data-bs-custom-class="beautifier"invece di data-bs-customClass="beautifier".

A partire da Bootstrap 5.2.0, tutti i componenti supportano un attributo di dati riservato sperimentaledata-bs-config che può ospitare una semplice configurazione del componente come una stringa JSON. Quando un elemento ha data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"attributi, il titlevalore finale sarà 456e gli attributi di dati separati sovrascriveranno i valori forniti su data-bs-config. Inoltre, gli attributi di dati esistenti sono in grado di ospitare valori JSON come data-bs-delay='{"show":0,"hide":150}'.

Nome Tipo Predefinito Descrizione
interval numero 5000 La quantità di tempo di ritardo tra il ciclo automatico di un elemento.
keyboard booleano true Se il carosello deve reagire agli eventi della tastiera.
pause stringa, booleano "hover" Se impostato su "hover", mette in pausa il ciclo del carosello mouseentere riprende il ciclo del carosello mouseleave. Se impostato su false, il passaggio del mouse sopra il carosello non lo metterà in pausa. Sui dispositivi abilitati al tocco, quando è impostato su "hover", il ciclo si interrompe touchend(una volta che l'utente ha terminato di interagire con il carosello) per due intervalli, prima di riprendere automaticamente. Questo è in aggiunta al comportamento del mouse.
ride stringa, booleano false Se impostato su true, riproduce automaticamente il carosello dopo che l'utente ha eseguito manualmente il ciclo del primo elemento. Se impostato su "carousel", riproduce automaticamente il carosello al caricamento.
touch booleano true Se il carosello deve supportare le interazioni di scorrimento a sinistra/destra sui dispositivi touchscreen.
wrap booleano true Se il carosello deve scorrere continuamente o avere arresti bruschi.

Metodi

Metodi e transizioni asincrone

Tutti i metodi API sono asincroni e avviano una transizione . Ritornano al chiamante non appena la transizione è iniziata ma prima che termini . Inoltre, una chiamata al metodo su un componente in transizione verrà ignorata .

Consulta la nostra documentazione JavaScript per ulteriori informazioni .

Puoi creare un'istanza del carosello con il costruttore del carosello, ad esempio, per inizializzare con opzioni aggiuntive e iniziare a scorrere gli elementi:

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: false
})
Metodo Descrizione
cycle Scorre gli elementi del carosello da sinistra a destra.
dispose Distrugge il carosello di un elemento. (Rimuove i dati memorizzati sull'elemento DOM)
getInstance Metodo statico che ti consente di ottenere l'istanza del carosello associata a un elemento DOM, puoi usarlo in questo modo: bootstrap.Carousel.getInstance(element).
getOrCreateInstance Metodo statico che restituisce un'istanza carosello associata a un elemento DOM o ne crea una nuova nel caso non sia stata inizializzata. Puoi usarlo in questo modo: bootstrap.Carousel.getOrCreateInstance(element).
next Passa all'elemento successivo. Ritorna al chiamante prima che venga mostrato l'elemento successivo (ad es. prima slid.bs.carouselche si verifichi l'evento).
nextWhenVisible Non passare al carosello successivo quando la pagina non è visibile o il carosello o il relativo genitore non sono visibili. Ritorna al chiamante prima che sia stato mostrato l'elemento di destinazione .
pause Impedisce al carosello di scorrere gli oggetti.
prev Passa all'elemento precedente. Ritorna al chiamante prima che sia stato mostrato l'elemento precedente (ad es. prima slid.bs.carouselche si verifichi l'evento).
to Fa scorrere il carosello su un fotogramma particolare (basato su 0, simile a una matrice). Ritorna al chiamante prima che l'elemento di destinazione sia stato mostrato (ad esempio, prima slid.bs.carouselche si verifichi l'evento).

Eventi

La classe del carosello di Bootstrap espone due eventi per l'aggancio alla funzionalità del carosello. Entrambi gli eventi hanno le seguenti proprietà aggiuntive:

  • direction: La direzione in cui scorre il carosello (o "left"o "right").
  • relatedTarget: l'elemento DOM che viene inserito come elemento attivo.
  • from: L'indice dell'elemento corrente
  • to: L'indice dell'elemento successivo

Tutti gli eventi del carosello vengono attivati ​​sul carosello stesso (cioè al <div class="carousel">).

Tipo di evento Descrizione
slid.bs.carousel Scattato quando il carosello ha completato la sua transizione di diapositiva.
slide.bs.carousel Si attiva immediatamente quando slideviene richiamato il metodo dell'istanza. 
const myCarousel = document.getElementById('myCarousel')

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