in English

JavaScript

Hirupkeun Bootstrap sareng plugins JavaScript pilihan urang. Diajar ngeunaan unggal plugin, data kami sareng pilihan API programmatic, sareng seueur deui.

Dina kaca ieu

Individu atawa disusun

Plugins tiasa dilebetkeun masing-masing (nganggo individu Bootstrap js/dist/*.js), atanapi sadayana sakaligus nganggo bootstrap.jsatanapi anu diminified bootstrap.min.js(henteu kalebet duanana).

Upami anjeun nganggo bundler (Webpack, Parcel, Vite…), anjeun tiasa nganggo /js/dist/*.jsfile anu siap UMD.

Pamakéan sareng kerangka JavaScript

Nalika Bootstrap CSS tiasa dianggo sareng kerangka naon waé, Bootstrap JavaScript henteu sapinuhna cocog sareng kerangka JavaScript sapertos React, Vue, sareng Angular anu nganggap pangaweruh lengkep ngeunaan DOM. Boh Bootstrap sareng kerangka tiasa nyobian mutasi unsur DOM anu sami, nyababkeun bug sapertos dropdown anu macét dina posisi "buka".

Alternatif anu langkung saé pikeun anu nganggo kerangka ieu nyaéta ngagunakeun pakét khusus kerangka tinimbang Bootstrap JavaScript. Ieu sababaraha pilihan anu pang populerna:

React: React Bootstrap
Vue: BootstrapVue (ayeuna ngan ngadukung Vue 2 sareng Bootstrap 4)
Sudut: ng-bootstrap

Ngagunakeun Bootstrap salaku modul a

Coba sorangan! Unduh kode sumber sareng demo damel pikeun ngagunakeun Bootstrap salaku modul ES tina gudang twbs/conto . Anjeun oge bisa muka conto dina StackBlitz .

Urang nyadiakeun versi Bootstrap diwangun salaku ESM( bootstrap.esm.jsjeung bootstrap.esm.min.js) nu ngidinan Anjeun pikeun make Bootstrap salaku modul dina browser nu, lamun panyungsi anjeun sasaran ngarojong eta .

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

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

Dibandingkeun JS bundlers, ngagunakeun ESM dina browser merlukeun anjeun ngagunakeun jalur lengkep sareng filename tinimbang nami modul. Baca langkung seueur ngeunaan modul JS dina browser. Éta pisan sababna naha urang nganggo 'bootstrap.esm.min.js'tinimbang di 'bootstrap'luhur. Nanging, ieu langkung rumit ku katergantungan Popper urang, anu ngimpor Popper kana JavaScript urang sapertos kieu:

import * as Popper from "@popperjs/core"

Upami anjeun nyobian sapertos kieu, anjeun bakal ningali kasalahan dina konsol sapertos kieu:

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

Pikeun ngalereskeun ieu, anjeun tiasa nganggo hiji importmapngabéréskeun nami modul sawenang pikeun ngalengkepan jalur. Upami panyungsi anjeun henteu ngadukung importmap, anjeun kedah nganggo proyék es-module-shims . Ieu kumaha jalanna pikeun Bootstrap sareng 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>

Depéndensi

Sababaraha plugins sareng komponén CSS gumantung kana plugins séjén. Upami anjeun ngalebetkeun plugin masing-masing, pastikeun pikeun pariksa katergantungan ieu dina dokumén.

dropdowns kami, popovers, sarta tooltips ogé gumantung kana Popper .

Atribut data

Ampir kabéh plugins Bootstrap bisa diaktipkeun jeung ngonpigurasi ngaliwatan HTML nyalira kalayan atribut data (cara pikaresep urang ngagunakeun fungsionalitas JavaScript). Pastikeun ngan ukur nganggo hiji set atribut data dina hiji unsur (contona, anjeun moal tiasa memicu tooltip sareng modal tina tombol anu sami.)

Salaku pilihan bisa diliwatan via atribut data atawa JavaScript, anjeun bisa append hiji ngaran pilihan pikeun data-bs-, sakumaha dina data-bs-animation="{value}". Pastikeun pikeun ngarobah tipe kasus tina ngaran pilihan tina " camelCase " pikeun " kebab-case " nalika ngalirkeun pilihan ngaliwatan atribut data. Contona, make data-bs-custom-class="beautifier"tinimbang data-bs-customClass="beautifier".

Salaku Bootstrap 5.2.0, sadaya komponén ngarojong hiji atribut data ditangtayungan eksperimendata-bs-config nu bisa imah konfigurasi komponén basajan salaku string JSON. Lamun hiji unsur boga data-bs-config='{"delay":0, "title":123}'jeung data-bs-title="456"atribut, nilai final titlebakal 456jeung atribut data misah bakal override nilai dibikeun dina data-bs-config. Salaku tambahan, atribut data anu aya tiasa ngeusian nilai JSON sapertos data-bs-delay='{"show":0,"hide":150}'.

Pamilih

Kami nganggo asli querySelectorsareng querySelectorAllmetode pikeun naroskeun elemen DOM pikeun alesan kinerja, janten anjeun kedah nganggo pamilih anu sah . Upami anjeun nganggo pamilih khusus sapertos collapse:Example, pastikeun pikeun ngémutan aranjeunna.

Kajadian

Bootstrap nyayogikeun acara khusus pikeun kalolobaan tindakan unik plugins. Sacara umum, ieu datangna dina bentuk participle infinitive jeung kaliwat - dimana infinitive (ex. show) dipicu dina mimiti hiji acara, sarta formulir participle kaliwat na (ex. shown) dipicu nalika parantosan hiji aksi.

Kabéh acara infinitive nyadiakeun preventDefault()fungsionalitas. Ieu nyadiakeun kamampuhan pikeun ngeureunkeun palaksanaan hiji aksi saméméh dimimitian. Balik palsu ti pawang acara ogé bakal otomatis nelepon preventDefault().

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

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

Programmatic API

Sadaya konstruktor nampi pilihan obyék atanapi henteu nanaon (anu ngamimitian plugin kalayan paripolah standarna):

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

Upami anjeun hoyong kéngingkeun conto plugin khusus, unggal plugin ngungkabkeun getInstancemetodeu. Contona, pikeun meunangkeun instance langsung tina unsur:

bootstrap.Popover.getInstance(myPopoverEl)

Metoda ieu bakal balik deui nulllamun hiji conto teu ngagagas leuwih unsur dipénta.

Alternatipna, getOrCreateInstancebisa dipaké pikeun meunangkeun instance pakait sareng unsur DOM, atawa nyieun nu anyar bisi teu initialized.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Upami hiji conto teu diinisialisasi, éta tiasa nampi sareng nganggo obyék konfigurasi opsional salaku argumen kadua.

pamilih CSS di konstruktor

Salian metode getInstancesareng getOrCreateInstance, sadaya konstruktor plugin tiasa nampi unsur DOM atanapi pamilih CSS anu valid salaku argumen anu munggaran. Unsur plugin kapanggih sareng querySelectormetodeu sabab plugins kami ngan ukur ngadukung hiji unsur.

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 Asynchronous jeung transisi

Sadaya metodeu API programmatic henteu sinkron sareng uih deui ka panelepon saatos transisi dimimitian, tapi sateuacan réngsé . Pikeun ngaéksekusi tindakan saatos transisi parantos réngsé, anjeun tiasa ngadangukeun acara anu saluyu.

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

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

Sajaba ti éta, panggero métode dina komponén transisi bakal dipaliré .

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`métode

Sanaos sigana leres ngagunakeun disposemetodeu saatosna hide(), éta bakal nyababkeun hasil anu salah. Ieu conto pamakean masalah:

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

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

Setélan standar

Anjeun tiasa ngarobih setélan standar pikeun plugin ku ngarobih Constructor.Defaultobyék plugin:

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

Métode jeung sipat

Unggal plugin Bootstrap ngungkabkeun metode sareng sipat statik di handap ieu.

Métode	Katerangan
`dispose`	Ngancurkeun modal hiji unsur. (Ngahapus data anu disimpen dina unsur DOM)
`getInstance`	Métode statik anu ngamungkinkeun anjeun kéngingkeun conto modal anu aya hubunganana sareng unsur DOM.
`getOrCreateInstance`	Metodeu statik anu ngamungkinkeun anjeun kéngingkeun conto modal anu aya hubunganana sareng unsur DOM, atanapi ngadamel anu énggal upami henteu diinisialisasi.

sipat statik	Katerangan
`NAME`	Mulih nami plugin. (Conto: `bootstrap.Tooltip.NAME`)
`VERSION`	Versi masing-masing plugins Bootstrap tiasa diaksés ngalangkungan `VERSION`hak milik konstruktor plugin (Conto: `bootstrap.Tooltip.VERSION`)

Sanitizer

Tooltips sareng Popovers nganggo sanitizer anu diwangun pikeun ngabersihan pilihan anu nampi HTML.

Nilai standar allowListnyaéta kieu:

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: []
}

Upami anjeun hoyong nambihan nilai anyar kana standar ieu allowListanjeun tiasa ngalakukeun ieu:

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)

Upami anjeun hoyong ngalangkungan sanitizer kami sabab anjeun langkung resep ngagunakeun perpustakaan khusus, contona DOMPurify , anjeun kedah ngalakukeun ieu:

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

Optionally ngagunakeun jQuery

Anjeun teu kedah jQuery di Bootstrap 5 , tapi masih mungkin ngagunakeun komponén kami kalawan jQuery. Upami Bootstrap ngadeteksi jQuerydina windowobyék, éta bakal nambihan sadaya komponén kami dina sistem plugin jQuery. Ieu ngamungkinkeun anjeun pikeun ngalakukeun ieu:

$('[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

Sami lumaku pikeun komponén urang lianna.

Taya konflik

Kadang-kadang perlu ngagunakeun plugins Bootstrap sareng kerangka UI anu sanés. Dina kaayaan ieu, tabrakan ngaranspasi kadang bisa lumangsung. Upami ieu kajantenan, anjeun tiasa nelepon .noConflictkana plugin anu anjeun hoyong balikkeun nilaina.

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

Bootstrap henteu sacara resmi ngadukung perpustakaan JavaScript pihak katilu sapertos Prototype atanapi jQuery UI. Sanaos .noConflictacara sareng namespaced, meureun aya masalah kasaluyuan anu anjeun kedah ngalereskeun nyalira.

acara jQuery

Bootstrap bakal ngadeteksi jQuery upami jQueryaya dina windowobyék sareng teu aya data-bs-no-jqueryatribut anu dipasang dina <body>. Lamun jQuery kapanggih, Bootstrap bakal emit acara berkat sistem acara jQuery urang. Janten upami anjeun hoyong ngadangukeun acara Bootstrap, anjeun kedah nganggo metode jQuery ( .on, .one) tibatan addEventListener.

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

JavaScript ditumpurkeun

Plugin Bootstrap teu gaduh fallback khusus nalika JavaScript ditumpurkeun. Upami anjeun paduli kana pangalaman pangguna dina hal ieu, paké <noscript>pikeun ngajelaskeun kaayaan (sareng kumaha cara ngaktipkeun deui JavaScript) ka pangguna anjeun, sareng / atanapi tambahkeun fallbacks adat anjeun sorangan.