Langkau ke kandungan utama Langkau ke navigasi dokumen
Check
in English

JavaScript

Hidupkan Bootstrap dengan pemalam JavaScript pilihan kami. Ketahui tentang setiap pemalam, data kami dan pilihan API terprogram dan banyak lagi.

Pada halaman ini

Individu atau disusun

Pemalam boleh disertakan secara individu (menggunakan individu Bootstrap js/dist/*.js), atau sekali gus menggunakan bootstrap.jsatau diperkecilkan bootstrap.min.js(jangan sertakan kedua-duanya).

Jika anda menggunakan bundler (Webpack, Parcel, Vite…), anda boleh menggunakan /js/dist/*.jsfail yang sedia UMD.

Penggunaan dengan rangka kerja JavaScript

Walaupun CSS Bootstrap boleh digunakan dengan mana-mana rangka kerja, JavaScript Bootstrap tidak serasi sepenuhnya dengan rangka kerja JavaScript seperti React, Vue dan Angular yang menganggap pengetahuan penuh tentang DOM. Kedua-dua Bootstrap dan rangka kerja mungkin cuba memutasi elemen DOM yang sama, mengakibatkan pepijat seperti dropdown yang tersekat dalam kedudukan "terbuka".

Alternatif yang lebih baik bagi mereka yang menggunakan rangka kerja jenis ini ialah menggunakan pakej khusus rangka kerja dan bukannya JavaScript Bootstrap. Berikut ialah beberapa pilihan yang paling popular:

Menggunakan Bootstrap sebagai modul

Cubalah sendiri! Muat turun kod sumber dan demo berfungsi untuk menggunakan Bootstrap sebagai modul ES daripada repositori twbs/examples . Anda juga boleh membuka contoh dalam StackBlitz .

Kami menyediakan versi Bootstrap yang dibina sebagai ESM( bootstrap.esm.jsdan bootstrap.esm.min.js) yang membolehkan anda menggunakan Bootstrap sebagai modul dalam penyemak imbas, jika pelayar sasaran anda menyokongnya .

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

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

Berbanding dengan pengikat JS, menggunakan ESM dalam penyemak imbas memerlukan anda menggunakan laluan penuh dan nama fail dan bukannya nama modul. Baca lebih lanjut mengenai modul JS dalam penyemak imbas. Itulah sebabnya kami menggunakan 'bootstrap.esm.min.js'bukannya di 'bootstrap'atas. Walau bagaimanapun, ini lebih rumit oleh pergantungan Popper kami, yang mengimport Popper ke dalam JavaScript kami seperti:

import * as Popper from "@popperjs/core"

Jika anda mencuba ini apa adanya, anda akan melihat ralat dalam konsol seperti berikut:

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

Untuk membetulkannya, anda boleh menggunakan importmapuntuk menyelesaikan nama modul sewenang-wenangnya untuk melengkapkan laluan. Jika penyemak imbas sasaran anda tidak menyokong importmap, anda perlu menggunakan projek es-module-shims . Begini cara ia berfungsi 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>

Kebergantungan

Sesetengah pemalam dan komponen CSS bergantung pada pemalam lain. Jika anda memasukkan pemalam secara individu, pastikan anda menyemak kebergantungan ini dalam dokumen.

Dropdown, popover dan petua alat kami juga bergantung pada Popper .

Atribut data

Hampir semua pemalam Bootstrap boleh didayakan dan dikonfigurasikan melalui HTML sahaja dengan atribut data (cara pilihan kami untuk menggunakan fungsi JavaScript). Pastikan anda hanya menggunakan satu set atribut data pada satu elemen (cth, anda tidak boleh mencetuskan petua alat dan modal daripada butang yang sama.)

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}'.

Pemilih

Kami menggunakan kaedah asli querySelectordan querySelectorAllkaedah untuk menanyakan elemen DOM atas sebab prestasi, jadi anda mesti menggunakan pemilih yang sah . Jika anda menggunakan pemilih khas seperti collapse:Example, pastikan anda melepaskannya.

Peristiwa

Bootstrap menyediakan acara tersuai untuk kebanyakan tindakan unik pemalam. Secara amnya, ini datang dalam bentuk infinitif dan participle lepas - di mana infinitif (cth. show) dicetuskan pada permulaan acara, dan bentuk participle past (cth. shown) dicetuskan apabila selesai tindakan.

Semua peristiwa infinitif menyediakan preventDefault()fungsi. Ini memberikan keupayaan untuk menghentikan pelaksanaan tindakan sebelum ia bermula. Mengembalikan palsu daripada pengendali acara juga akan memanggil secara automatik preventDefault().

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

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

API Programmatik

Semua pembina menerima objek pilihan pilihan atau tiada apa-apa (yang memulakan pemalam dengan tingkah laku lalainya):

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 contoh pemalam tertentu, setiap pemalam mendedahkan getInstancekaedah. Contohnya, untuk mendapatkan semula tika secara langsung daripada elemen:

bootstrap.Popover.getInstance(myPopoverEl)

Kaedah ini akan kembali nulljika kejadian tidak dimulakan atas elemen yang diminta.

Sebagai alternatif, getOrCreateInstanceboleh digunakan untuk mendapatkan contoh yang dikaitkan dengan elemen DOM, atau mencipta yang baharu sekiranya ia tidak dimulakan.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Sekiranya contoh tidak dimulakan, ia boleh menerima dan menggunakan objek konfigurasi pilihan sebagai hujah kedua.

Pemilih CSS dalam pembina

Selain kaedah getInstancedan getOrCreateInstance, semua pembina pemalam boleh menerima elemen DOM atau pemilih CSS yang sah sebagai hujah pertama. Elemen pemalam ditemui dengan querySelectorkaedah kerana pemalam kami hanya menyokong 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 peralihan tak segerak

Semua kaedah API terprogram adalah tak segerak dan kembali kepada pemanggil sebaik sahaja peralihan dimulakan, tetapi sebelum ia tamat . Untuk melaksanakan tindakan setelah peralihan selesai, anda boleh mendengar acara yang sepadan.

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

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

Selain itu, panggilan kaedah pada komponen peralihan 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 !!

disposekaedah

Walaupun nampaknya betul untuk menggunakan disposekaedah sejurus selepas hide(), ia akan membawa kepada keputusan yang salah. Berikut ialah contoh penggunaan masalah:

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

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

Tetapan lalai

Anda boleh menukar tetapan lalai untuk pemalam dengan mengubah suai Constructor.Defaultobjek pemalam:

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

Kaedah dan sifat

Setiap pemalam Bootstrap mendedahkan kaedah dan sifat statik berikut.

Kaedah Penerangan
dispose Memusnahkan modal elemen. (Mengalih keluar data yang disimpan pada elemen DOM)
getInstance Kaedah statik yang membolehkan anda mendapatkan contoh modal yang dikaitkan dengan elemen DOM.
getOrCreateInstance Kaedah statik yang membolehkan anda mendapatkan contoh modal yang dikaitkan dengan elemen DOM, atau mencipta yang baharu sekiranya ia tidak dimulakan.
Harta statik Penerangan
NAME Mengembalikan nama pemalam. (Contoh: bootstrap.Tooltip.NAME)
VERSION Versi setiap pemalam Bootstrap boleh diakses melalui VERSIONharta pembina pemalam (Contoh: bootstrap.Tooltip.VERSION)

Sanitizer

Petua alat dan Popovers menggunakan sanitizer terbina dalam kami untuk membersihkan pilihan yang menerima HTML.

Nilai lalai allowListadalah seperti 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 menambah nilai baharu pada lalai ini allowList, anda boleh melakukan perkara 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 memintas sanitizer kami kerana anda lebih suka menggunakan perpustakaan khusus, contohnya DOMPuify , anda harus melakukan perkara berikut:

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

Secara pilihan menggunakan jQuery

Anda tidak memerlukan jQuery dalam Bootstrap 5 , tetapi masih boleh menggunakan komponen kami dengan jQuery. Jika Bootstrap mengesan jQuerydalam windowobjek, ia akan menambah semua komponen kami dalam sistem pemalam jQuery. Ini membolehkan anda melakukan perkara 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

Begitu juga dengan komponen kami yang lain.

Tiada konflik

Kadangkala perlu menggunakan pemalam Bootstrap dengan rangka kerja UI yang lain. Dalam keadaan ini, perlanggaran ruang nama kadangkala boleh berlaku. Jika ini berlaku, anda boleh menghubungi .noConflictpemalam 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 rasmi menyokong perpustakaan JavaScript pihak ketiga seperti Prototaip atau UI jQuery. Walaupun .noConflictacara dan ruang nama, mungkin terdapat masalah keserasian yang perlu anda selesaikan sendiri.

acara jQuery

Bootstrap akan mengesan jQuery jika jQueryterdapat dalam windowobjek dan tiada data-bs-no-jqueryatribut ditetapkan pada <body>. Jika jQuery ditemui, Bootstrap akan memancarkan peristiwa terima kasih kepada sistem acara jQuery. Jadi, jika anda ingin mendengar acara Bootstrap, anda perlu menggunakan kaedah jQuery ( .on, .one) dan bukannya addEventListener.

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

JavaScript dilumpuhkan

Pemalam Bootstrap tidak mempunyai sandaran khas apabila JavaScript dilumpuhkan. Jika anda mengambil berat tentang pengalaman pengguna dalam kes ini, gunakan <noscript>untuk menerangkan situasi (dan cara mendayakan semula JavaScript) kepada pengguna anda dan/atau menambah sandaran tersuai anda sendiri.