Langkau ke kandungan utama Langkau ke navigasi dokumen
Check
in English

karusel

Komponen tayangan slaid untuk melayari elemen—imej atau slaid teks—seperti karusel.

Pada halaman ini

Bagaimana ia berfungsi

Karusel ialah tayangan slaid untuk berbasikal melalui satu siri kandungan, dibina dengan perubahan CSS 3D dan sedikit JavaScript. Ia berfungsi dengan satu siri imej, teks atau penanda tersuai. Ia juga termasuk sokongan untuk kawalan dan penunjuk sebelumnya/seterusnya.

Dalam penyemak imbas di mana API Keterlihatan Halaman disokong, karusel akan mengelakkan gelongsor apabila halaman web tidak kelihatan kepada pengguna (seperti apabila tab penyemak imbas tidak aktif, tetingkap penyemak imbas diminimumkan, dsb.).

Kesan animasi komponen ini bergantung pada prefers-reduced-motionpertanyaan media. Lihat bahagian gerakan yang dikurangkan dalam dokumentasi kebolehaksesan kami .

Harap maklum bahawa karusel bersarang tidak disokong dan karusel biasanya tidak mematuhi piawaian kebolehaksesan.

Contoh

Karusel tidak menormalkan dimensi slaid secara automatik. Oleh itu, anda mungkin perlu menggunakan utiliti tambahan atau gaya tersuai untuk saiz kandungan yang sesuai. Walaupun karusel menyokong kawalan dan penunjuk sebelumnya/seterusnya, ia tidak diperlukan secara eksplisit. Tambah dan sesuaikan mengikut kesesuaian anda.

Kelas .activeperlu ditambahkan pada salah satu slaid jika tidak, karusel tidak akan kelihatan. Juga pastikan anda menetapkan unik idpada .carouseluntuk kawalan pilihan, terutamanya jika anda menggunakan berbilang karusel pada satu halaman. Elemen kawalan dan penunjuk mesti mempunyai data-bs-targetatribut (atau hrefuntuk pautan) yang sepadan iddengan .carouselelemen tersebut.

Slaid sahaja

Berikut ialah karusel dengan slaid sahaja. Perhatikan kehadiran imej karusel .d-blockdan .w-100pada untuk mengelakkan penjajaran imej lalai penyemak imbas.

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>

Dengan kawalan

Menambah kawalan sebelumnya dan seterusnya. Kami mengesyorkan menggunakan <button>elemen, tetapi anda juga boleh menggunakan <a>elemen dengan 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>

Dengan penunjuk

Anda juga boleh menambah penunjuk pada karusel, di samping kawalan juga.

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>

Dengan kapsyen

Tambahkan kapsyen pada slaid anda dengan mudah dengan .carousel-captionelemen dalam mana-mana .carousel-item. Ia boleh disembunyikan dengan mudah pada port pandangan yang lebih kecil, seperti yang ditunjukkan di bawah, dengan utiliti paparan pilihan . Kami menyembunyikannya pada mulanya dengan .d-nonedan membawanya kembali pada peranti bersaiz sederhana dengan .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>

Pudar silang

Tambahkan .carousel-fadepada karusel anda untuk menghidupkan slaid dengan peralihan pudar dan bukannya slaid. Bergantung pada kandungan karusel anda (cth, slaid teks sahaja), anda mungkin mahu menambah .bg-bodyatau beberapa CSS tersuai pada .carousel-items untuk pemudar silang yang betul.

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>

Tambahkan data-bs-interval=""pada a .carousel-itemuntuk menukar jumlah masa untuk menangguhkan antara berbasikal secara automatik ke item seterusnya.

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>

Lumpuhkan leretan sentuhan

Karusel menyokong meleret ke kiri/kanan pada peranti skrin sentuh untuk bergerak antara slaid. Ini boleh dilumpuhkan menggunakan data-bs-touchatribut. Contoh di bawah juga tidak termasuk data-bs-rideatribut supaya ia tidak automain.

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>

Varian gelap

Tambahkan .carousel-darkpada .carouselkawalan, penunjuk dan kapsyen yang lebih gelap. Kawalan telah diterbalikkan daripada isian putih lalainya dengan sifat filterCSS. Kapsyen dan kawalan mempunyai pembolehubah Sass tambahan yang menyesuaikan colordan 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>

Peralihan tersuai

Tempoh peralihan .carousel-itemboleh ditukar dengan $carousel-transition-durationpembolehubah Sass sebelum menyusun atau gaya tersuai jika anda menggunakan CSS yang disusun. Jika berbilang peralihan digunakan, pastikan peralihan transformasi ditakrifkan terlebih dahulu (cth transition: transform 2s ease, opacity .5s ease-out).

Sass

Pembolehubah

Pembolehubah untuk semua karusel:

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

Pembolehubah untuk karusel gelap :

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

Penggunaan

Melalui atribut data

Gunakan atribut data untuk mengawal kedudukan karusel dengan mudah. data-bs-slidemenerima kata kunci prevatau next, yang mengubah kedudukan slaid berbanding kedudukan semasanya. Sebagai alternatif, gunakan data-bs-slide-tountuk menghantar indeks slaid mentah ke karusel data-bs-slide-to="2", yang mengalihkan kedudukan slaid kepada indeks tertentu bermula dengan 0.

Atribut data-bs-ride="carousel"digunakan untuk menandakan karusel sebagai animasi bermula pada pemuatan halaman. Jika anda tidak menggunakan data-bs-ride="carousel"untuk memulakan karusel anda, anda perlu memulakannya sendiri. Ia tidak boleh digunakan dalam kombinasi dengan (berlebihan dan tidak perlu) pemula JavaScript eksplisit bagi karusel yang sama.

Melalui JavaScript

Panggil karusel secara manual dengan:

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

Pilihan

Memandangkan pilihan boleh dihantar melalui atribut data atau JavaScript, anda boleh menambahkan nama pilihan pada data-bs-, seperti dalam data-bs-animation="{value}". Pastikan anda menukar jenis kes bagi nama pilihan daripada " camelCase " kepada " kebab-case " apabila menghantar pilihan melalui atribut data. Sebagai contoh, gunakan data-bs-custom-class="beautifier"bukannya data-bs-customClass="beautifier".

Mulai Bootstrap 5.2.0, semua komponen menyokong atribut data simpanan percubaandata-bs-config yang boleh menempatkan konfigurasi komponen ringkas sebagai rentetan JSON. Apabila elemen mempunyai data-bs-config='{"delay":0, "title":123}'dan data-bs-title="456"atribut, nilai akhir titleakan menjadi 456dan atribut data yang berasingan akan mengatasi nilai yang diberikan pada data-bs-config. Selain itu, atribut data sedia ada dapat menempatkan nilai JSON seperti data-bs-delay='{"show":0,"hide":150}'.

Nama taip Lalai Penerangan
interval nombor 5000 Jumlah masa untuk menangguhkan antara mengayuh item secara automatik.
keyboard boolean true Sama ada karusel harus bertindak balas terhadap peristiwa papan kekunci.
pause rentetan, boolean "hover" Jika ditetapkan kepada "hover", jeda kitaran karusel dihidupkan mouseenterdan sambung semula kitaran karusel dihidupkan mouseleave. Jika ditetapkan kepada false, melayang di atas karusel tidak akan menjedanya. Pada peranti yang didayakan sentuhan, apabila ditetapkan kepada "hover", berbasikal akan dijeda touchend(apabila pengguna selesai berinteraksi dengan karusel) selama dua selang, sebelum disambung semula secara automatik. Ini adalah tambahan kepada tingkah laku tetikus.
ride rentetan, boolean false Jika ditetapkan kepada true, automainkan karusel selepas pengguna mengitar item pertama secara manual. Jika ditetapkan kepada "carousel", automainkan karusel semasa dimuatkan.
touch boolean true Sama ada karusel harus menyokong interaksi leret kiri/kanan pada peranti skrin sentuh.
wrap boolean true Sama ada karusel perlu berkitar secara berterusan atau mempunyai hentian keras.

Kaedah

Kaedah dan peralihan tak segerak

Semua kaedah API adalah tak segerak dan mulakan peralihan . Mereka kembali kepada pemanggil sebaik sahaja peralihan dimulakan tetapi sebelum ia tamat . Selain itu, panggilan kaedah pada komponen peralihan akan diabaikan .

Lihat dokumentasi JavaScript kami untuk mendapatkan maklumat lanjut .

Anda boleh membuat contoh karusel dengan pembina karusel, sebagai contoh, untuk memulakan dengan pilihan tambahan dan mula melayari item:

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: false
})
Kaedah Penerangan
cycle Kitaran melalui item karusel dari kiri ke kanan.
dispose Memusnahkan karusel unsur. (Mengalih keluar data yang disimpan pada elemen DOM)
getInstance Kaedah statik yang membolehkan anda mendapatkan contoh karusel yang dikaitkan dengan elemen DOM, anda boleh menggunakannya seperti ini: bootstrap.Carousel.getInstance(element).
getOrCreateInstance Kaedah statik yang mengembalikan tika karusel yang dikaitkan dengan elemen DOM atau mencipta yang baharu sekiranya ia tidak dimulakan. Anda boleh menggunakannya seperti ini: bootstrap.Carousel.getOrCreateInstance(element).
next Kitaran ke item seterusnya. Kembali kepada pemanggil sebelum item seterusnya ditunjukkan (cth, sebelum slid.bs.carouselperistiwa berlaku).
nextWhenVisible Jangan kitar karusel ke seterusnya apabila halaman tidak kelihatan atau karusel atau induknya tidak kelihatan. Kembali kepada pemanggil sebelum item sasaran ditunjukkan .
pause Menghentikan karusel daripada berbasikal melalui item.
prev Kitaran ke item sebelumnya. Kembali kepada pemanggil sebelum item sebelumnya telah ditunjukkan (cth, sebelum slid.bs.carouselperistiwa berlaku).
to Mengitar karusel ke bingkai tertentu (berasaskan 0, serupa dengan tatasusunan). Kembali kepada pemanggil sebelum item sasaran ditunjukkan (cth, sebelum slid.bs.carouselperistiwa berlaku).

Peristiwa

Kelas karusel Bootstrap mendedahkan dua acara untuk menyambung ke fungsi karusel. Kedua-dua acara mempunyai sifat tambahan berikut:

  • direction: Arah di mana karusel sedang meluncur (sama ada "left"atau "right").
  • relatedTarget: Elemen DOM yang sedang meluncur ke tempatnya sebagai item aktif.
  • from: Indeks item semasa
  • to: Indeks item seterusnya

Semua acara karusel dilepaskan pada karusel itu sendiri (iaitu pada <div class="carousel">).

Jenis acara Penerangan
slid.bs.carousel Dipecat apabila karusel telah menyelesaikan peralihan slaidnya.
slide.bs.carousel Menyala serta-merta apabila slidekaedah contoh digunakan. 
const myCarousel = document.getElementById('myCarousel')

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