in English

JavaScript

Hidupkan Bootstrap dengan plugin JavaScript opsional kami. Pelajari tentang setiap plugin, data dan opsi API terprogram kami, dan banyak lagi.

Di halaman ini

Individu atau dikompilasi

Plugin dapat dimasukkan satu per satu (menggunakan Bootstrap's individual js/dist/*.js), atau sekaligus menggunakan bootstrap.jsatau yang diperkecil bootstrap.min.js(jangan sertakan keduanya).

Jika Anda menggunakan bundler (Webpack, Parcel, Vite…), Anda dapat menggunakan /js/dist/*.jsfile yang siap UMD.

Penggunaan dengan kerangka kerja JavaScript

Sementara CSS Bootstrap dapat digunakan dengan kerangka kerja apa pun, JavaScript Bootstrap tidak sepenuhnya kompatibel dengan kerangka kerja JavaScript seperti React, Vue, dan Angular yang mengasumsikan pengetahuan penuh tentang DOM. Bootstrap dan kerangka kerja mungkin mencoba untuk mengubah elemen DOM yang sama, menghasilkan bug seperti dropdown yang macet di posisi "terbuka".

Alternatif yang lebih baik bagi mereka yang menggunakan jenis kerangka kerja ini adalah dengan menggunakan paket khusus kerangka kerja daripada JavaScript Bootstrap. Berikut adalah beberapa opsi yang paling populer:

Bereaksi: Bereaksi Bootstrap
Vue: BootstrapVue (saat ini hanya mendukung Vue 2 dan Bootstrap 4)
Sudut: ng-bootstrap

Menggunakan Bootstrap sebagai modul

Cobalah sendiri! Unduh kode sumber dan demo kerja untuk menggunakan Bootstrap sebagai modul ES dari repositori twbs/examples . Anda juga dapat membuka contoh di StackBlitz .

Kami menyediakan versi Bootstrap yang dibangun sebagai ESM( bootstrap.esm.jsdan bootstrap.esm.min.js) yang memungkinkan Anda untuk menggunakan Bootstrap sebagai modul di browser, jika browser target Anda mendukungnya .

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

Dibandingkan dengan JS bundler, menggunakan ESM di browser mengharuskan Anda menggunakan path lengkap dan nama file alih-alih nama modul. Baca lebih lanjut tentang modul JS di browser. Itu sebabnya kami menggunakan 'bootstrap.esm.min.js'alih-alih di 'bootstrap'atas. Namun, ini semakin diperumit oleh ketergantungan Popper kami, yang mengimpor Popper ke dalam JavaScript kami seperti:

import * as Popper from "@popperjs/core"

Jika Anda mencoba ini apa adanya, Anda akan melihat kesalahan di konsol seperti berikut:

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

Untuk memperbaikinya, Anda dapat menggunakan an importmapuntuk menyelesaikan nama modul arbitrer untuk menyelesaikan jalur. Jika browser yang Anda targetkan tidak mendukung importmap, Anda harus menggunakan proyek es-module-shims . Berikut cara kerjanya untuk Bootstrap dan Popper:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

Ketergantungan

Beberapa plugin dan komponen CSS bergantung pada plugin lain. Jika Anda menyertakan plugin satu per satu, pastikan untuk memeriksa dependensi ini di dokumen.

Dropdown, popover, dan tooltips kami juga bergantung pada Popper .

Atribut data

Hampir semua plugin Bootstrap dapat diaktifkan dan dikonfigurasi melalui HTML saja dengan atribut data (cara pilihan kami menggunakan fungsionalitas JavaScript). Pastikan untuk hanya menggunakan satu set atribut data pada satu elemen (misalnya, Anda tidak dapat memicu tooltip dan modal dari tombol yang sama.)

Karena opsi dapat diteruskan melalui atribut data atau JavaScript, Anda dapat menambahkan nama opsi ke data-bs-, seperti pada data-bs-animation="{value}". Pastikan untuk mengubah jenis huruf dari nama opsi dari “ camelCase ” menjadi “ kebab-case ” saat meneruskan opsi melalui atribut data. Misalnya, gunakan data-bs-custom-class="beautifier"alih-alih data-bs-customClass="beautifier".

Pada Bootstrap 5.2.0, semua komponen mendukung atribut data cadangan eksperimentaldata-bs-config yang dapat menampung konfigurasi komponen sederhana sebagai string JSON. Ketika suatu elemen memiliki data-bs-config='{"delay":0, "title":123}'dan data-bs-title="456"atribut, nilai akhir titleakan menjadi 456dan atribut data yang terpisah akan menimpa nilai yang diberikan pada data-bs-config. Selain itu, atribut data yang ada dapat menampung nilai JSON seperti data-bs-delay='{"show":0,"hide":150}'.

pemilih

Kami menggunakan metode asli querySelectordan querySelectorAlluntuk mengkueri elemen DOM untuk alasan kinerja, jadi Anda harus menggunakan pemilih yang valid . Jika Anda menggunakan penyeleksi khusus seperti collapse:Example, pastikan untuk menghindarinya.

Acara

Bootstrap menyediakan acara khusus untuk sebagian besar tindakan unik plugin. Umumnya, ini datang dalam bentuk infinitive dan past participle - di mana infinitive (ex. show) dipicu pada awal suatu peristiwa, dan bentuk past participle-nya (ex. shown) dipicu pada penyelesaian suatu tindakan.

Semua peristiwa infinitif menyediakan preventDefault()fungsionalitas. Ini memberikan kemampuan untuk menghentikan eksekusi suatu tindakan sebelum dimulai. Mengembalikan false dari event handler juga akan secara otomatis memanggil preventDefault().

const myModal = document.querySelector('#myModal')

myModal.addEventListener('show.bs.modal', event => {
  if (!data) {
    return event.preventDefault() // stops modal from being shown
  }
})

API terprogram

Semua konstruktor menerima objek opsi opsional atau tidak sama sekali (yang memulai plugin dengan perilaku defaultnya):

const myModalEl = document.querySelector('#myModal')

const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

Jika Anda ingin mendapatkan instance plugin tertentu, setiap plugin menampilkan getInstancemetode. Misalnya, untuk mengambil instance langsung dari elemen:

bootstrap.Popover.getInstance(myPopoverEl)

Metode ini akan kembali nulljika sebuah instance tidak dimulai pada elemen yang diminta.

Atau, getOrCreateInstancedapat digunakan untuk mendapatkan instance yang terkait dengan elemen DOM, atau membuat yang baru jika tidak diinisialisasi.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Jika sebuah instance tidak diinisialisasi, ia dapat menerima dan menggunakan objek konfigurasi opsional sebagai argumen kedua.

Pemilih CSS di konstruktor

Selain metode getInstanceand getOrCreateInstance, semua konstruktor plugin dapat menerima elemen DOM atau pemilih CSS yang valid sebagai argumen pertama. Elemen plugin ditemukan dengan querySelectormetode ini karena plugin kami hanya mendukung satu elemen.

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

Fungsi dan transisi asinkron

Semua metode API terprogram bersifat asinkron dan kembali ke pemanggil setelah transisi dimulai, tetapi sebelum berakhir . Untuk menjalankan tindakan setelah transisi selesai, Anda dapat mendengarkan acara yang sesuai.

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Action to execute once the collapsible area is expanded
})

Selain itu, pemanggilan metode pada komponen transisi akan diabaikan .

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

`dispose`metode

Meskipun mungkin tampak benar untuk menggunakan disposemetode segera setelah hide(), itu akan menyebabkan hasil yang salah. Berikut ini contoh penggunaan masalah:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

Pengaturan default

Anda dapat mengubah pengaturan default untuk plugin dengan memodifikasi Constructor.Defaultobjek plugin:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

Metode dan properti

Setiap plugin Bootstrap memperlihatkan metode dan properti statis berikut.

metode	Keterangan
`dispose`	Menghancurkan modal elemen. (Menghapus data yang tersimpan pada elemen DOM)
`getInstance`	Metode statis yang memungkinkan Anda mendapatkan instance modal yang terkait dengan elemen DOM.
`getOrCreateInstance`	Metode statis yang memungkinkan Anda mendapatkan instance modal yang terkait dengan elemen DOM, atau membuat yang baru jika tidak diinisialisasi.

Properti statis	Keterangan
`NAME`	Mengembalikan nama plugin. (Contoh: `bootstrap.Tooltip.NAME`)
`VERSION`	Versi masing-masing plugin Bootstrap dapat diakses melalui `VERSION`properti konstruktor plugin (Contoh: `bootstrap.Tooltip.VERSION`)

pembersih

Tooltips dan Popovers menggunakan pembersih bawaan kami untuk membersihkan opsi yang menerima HTML.

Nilai defaultnya allowListadalah sebagai berikut:

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
const DefaultAllowlist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

Jika Anda ingin menambahkan nilai baru ke default ini, allowListAnda dapat melakukan hal berikut:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// To allow table elements
myDefaultAllowList.table = []

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ['data-bs-option']

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

Jika Anda ingin melewati pembersih kami karena Anda lebih suka menggunakan perpustakaan khusus, misalnya DOMPurify , Anda harus melakukan hal berikut:

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

Opsional menggunakan jQuery

Anda tidak memerlukan jQuery di Bootstrap 5 , tetapi masih memungkinkan untuk menggunakan komponen kami dengan jQuery. Jika Bootstrap mendeteksi jQuerydi windowobjek, itu akan menambahkan semua komponen kami di sistem plugin jQuery. Ini memungkinkan Anda untuk melakukan hal berikut:

$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration

$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration

$('#myTooltip').tooltip('show') // to trigger `show` method

Hal yang sama berlaku untuk komponen kami yang lain.

Tidak ada konflik

Terkadang perlu menggunakan plugin Bootstrap dengan kerangka kerja UI lainnya. Dalam keadaan ini, tabrakan namespace kadang-kadang dapat terjadi. Jika ini terjadi, Anda dapat memanggil .noConflictplugin yang ingin Anda kembalikan nilainya.

const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

Bootstrap tidak secara resmi mendukung library JavaScript pihak ketiga seperti Prototype atau jQuery UI. Terlepas dari .noConflictdan acara dengan namespace, mungkin ada masalah kompatibilitas yang perlu Anda perbaiki sendiri.

acara jQuery

Bootstrap akan mendeteksi jQuery jika jQueryada di windowobjek dan tidak ada data-bs-no-jqueryatribut yang disetel <body>. Jika jQuery ditemukan, Bootstrap akan memancarkan acara berkat sistem acara jQuery. Jadi jika Anda ingin mendengarkan acara Bootstrap, Anda harus menggunakan metode jQuery ( .on, .one) alih-alih addEventListener.

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})

JavaScript yang dinonaktifkan

Plugin Bootstrap tidak memiliki fallback khusus saat JavaScript dinonaktifkan. Jika Anda peduli dengan pengalaman pengguna dalam kasus ini, gunakan <noscript>untuk menjelaskan situasinya (dan cara mengaktifkan kembali JavaScript) kepada pengguna Anda, dan/atau menambahkan fallback khusus Anda sendiri.