JavaScript

Buhayin ang Bootstrap gamit ang aming mga opsyonal na plugin ng JavaScript. Matuto tungkol sa bawat plugin, aming data at mga opsyon sa programmatic na API, at higit pa.

Sa pahinang ito

Indibidwal o pinagsama-sama

Maaaring isama ang mga plugin nang isa-isa (gamit ang indibidwal na Bootstrap js/dist/*.js), o sabay-sabay gamit bootstrap.jso ang minified bootstrap.min.js(huwag isama ang pareho).

Kung gumagamit ka ng isang bundler (Webpack, Parcel, Vite...), maaari mong gamitin ang /js/dist/*.jsmga file na nakahanda sa UMD.

Paggamit sa JavaScript frameworks

Habang ang Bootstrap CSS ay maaaring gamitin sa anumang framework, ang Bootstrap JavaScript ay hindi ganap na tugma sa JavaScript frameworks tulad ng React, Vue, at Angular na may ganap na kaalaman sa DOM. Maaaring subukan ng Bootstrap at ng framework na i-mutate ang parehong elemento ng DOM, na nagreresulta sa mga bug tulad ng mga dropdown na na-stuck sa "bukas" na posisyon.

Ang isang mas mahusay na alternatibo para sa mga gumagamit ng ganitong uri ng mga framework ay ang paggamit ng isang framework-specific na package sa halip na ang Bootstrap JavaScript. Narito ang ilan sa mga pinakasikat na opsyon:

React: React Bootstrap
Vue: BootstrapVue (kasalukuyang sinusuportahan lamang ang Vue 2 at Bootstrap 4)
Angular: ng-bootstrap

Paggamit ng Bootstrap bilang isang module

Subukan ito sa iyong sarili! I-download ang source code at gumaganang demo para sa paggamit ng Bootstrap bilang ES module mula sa twbs/examples repository . Maaari mo ring buksan ang halimbawa sa StackBlitz .

Nagbibigay kami ng bersyon ng Bootstrap na binuo bilang ESM( bootstrap.esm.jsat bootstrap.esm.min.js) na nagbibigay-daan sa iyong gamitin ang Bootstrap bilang module sa browser, kung sinusuportahan ito ng iyong mga naka-target na browser .

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

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

Kung ikukumpara sa mga JS bundler, ang paggamit ng ESM sa browser ay nangangailangan sa iyo na gamitin ang buong path at filename sa halip na ang pangalan ng module. Magbasa nang higit pa tungkol sa mga module ng JS sa browser. Iyon ang dahilan kung bakit ginagamit namin 'bootstrap.esm.min.js'sa halip na nasa 'bootstrap'itaas. Gayunpaman, mas kumplikado ito ng aming dependency sa Popper, na nag-import ng Popper sa aming JavaScript tulad nito:

import * as Popper from "@popperjs/core"

Kung susubukan mo ito kung ano man, makakakita ka ng error sa console tulad ng sumusunod:

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

Upang ayusin ito, maaari kang gumamit ng isang importmapupang malutas ang mga arbitrary na pangalan ng module upang makumpleto ang mga landas. Kung hindi sinusuportahan ng iyong mga naka- target na browserimportmap ang , kakailanganin mong gamitin ang proyektong es-module-shims . Narito kung paano ito gumagana para sa Bootstrap at 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>

Dependencies

Ang ilang mga plugin at mga bahagi ng CSS ay nakasalalay sa iba pang mga plugin. Kung isa-isa kang magsasama ng mga plugin, tiyaking suriin ang mga dependency na ito sa mga doc.

Ang aming mga dropdown, popover, at tooltip ay nakadepende rin sa Popper .

Mga katangian ng data

Halos lahat ng mga plugin ng Bootstrap ay maaaring paganahin at i-configure sa pamamagitan ng HTML lamang na may mga katangian ng data (ang aming gustong paraan ng paggamit ng paggana ng JavaScript). Tiyaking gumamit lamang ng isang hanay ng mga katangian ng data sa isang elemento (hal., hindi ka makakapag-trigger ng tooltip at modal mula sa parehong button.)

Dahil maaaring maipasa ang mga opsyon sa pamamagitan ng mga katangian ng data o JavaScript, maaari kang magdagdag ng pangalan ng opsyon sa data-bs-, tulad ng sa data-bs-animation="{value}". Siguraduhing baguhin ang uri ng case ng pangalan ng opsyon mula sa " camelCase " sa " kebab-case " kapag ipinapasa ang mga opsyon sa pamamagitan ng mga katangian ng data. Halimbawa, gamitin data-bs-custom-class="beautifier"sa halip na data-bs-customClass="beautifier".

Mula sa Bootstrap 5.2.0, sinusuportahan ng lahat ng mga bahagi ang isang pang- eksperimentong nakalaan na katangian ng data data-bs-configna maaaring maglagay ng simpleng configuration ng bahagi bilang isang string ng JSON. Kapag ang isang elemento ay may data-bs-config='{"delay":0, "title":123}'at data-bs-title="456"mga katangian, ang huling titlehalaga ay magiging 456at ang hiwalay na mga katangian ng data ay mag-o-override sa mga halagang ibinigay sa data-bs-config. Bilang karagdagan, ang mga kasalukuyang katangian ng data ay nakakapaglagay ng mga halaga ng JSON tulad ng data-bs-delay='{"show":0,"hide":150}'.

Mga pumipili

Ginagamit namin ang native querySelectorat mga querySelectorAllpamamaraan upang mag-query ng mga elemento ng DOM para sa mga kadahilanan ng pagganap, kaya dapat kang gumamit ng mga wastong tagapili . Kung gumagamit ka ng mga espesyal na tagapili tulad ng collapse:Example, tiyaking takasan ang mga ito.

Mga kaganapan

Nagbibigay ang Bootstrap ng mga custom na kaganapan para sa mga natatanging pagkilos ng karamihan sa mga plugin. Sa pangkalahatan, ang mga ito ay dumating sa isang infinitive at past participle form - kung saan ang infinitive (hal. show) ay na-trigger sa simula ng isang kaganapan, at ang past participle form nito (hal. shown) ay na-trigger sa pagkumpleto ng isang aksyon.

Ang lahat ng infinitive na kaganapan ay nagbibigay ng preventDefault()functionality. Nagbibigay ito ng kakayahang ihinto ang pagpapatupad ng isang aksyon bago ito magsimula. Ang pagbabalik ng false mula sa isang event handler ay awtomatikong tatawag preventDefault().

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

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

Programmatic API

Lahat ng mga konstruktor ay tumatanggap ng opsyonal na bagay na opsyon o wala (na nagpasimula ng isang plugin na may default na gawi nito):

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

Kung gusto mong makakuha ng partikular na instance ng plugin, ang bawat plugin ay naglalantad ng getInstanceparaan. Halimbawa, upang makuha ang isang instance nang direkta mula sa isang elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Babalik ang pamamaraang nullito kung ang isang instance ay hindi pinasimulan sa hiniling na elemento.

Bilang kahalili, getOrCreateInstancemaaaring magamit upang makuha ang instance na nauugnay sa isang elemento ng DOM, o lumikha ng bago kung sakaling hindi ito nasimulan.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Kung sakaling hindi nasimulan ang isang instance, maaari itong tanggapin at gumamit ng opsyonal na configuration object bilang pangalawang argumento.

Mga tagapili ng CSS sa mga konstruktor

Bilang karagdagan sa getInstanceat mga getOrCreateInstancepamamaraan, lahat ng mga tagabuo ng plugin ay maaaring tumanggap ng isang elemento ng DOM o isang wastong CSS selector bilang unang argumento. Ang mga elemento ng plugin ay matatagpuan sa querySelectorpamamaraan dahil sinusuportahan lamang ng aming mga plugin ang isang elemento.

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')

Mga asynchronous na function at transition

Ang lahat ng mga pamamaraan ng programmatic API ay asynchronous at bumalik sa tumatawag kapag nagsimula na ang paglipat, ngunit bago ito matapos . Upang maisagawa ang isang aksyon kapag nakumpleto na ang paglipat, maaari kang makinig sa kaukulang kaganapan.

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

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

Bilang karagdagan, babalewalain ang isang method call sa isang transitioning component .

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`paraan

Bagama't mukhang tama na gamitin ang disposepamamaraan kaagad pagkatapos ng hide(), hahantong ito sa mga maling resulta. Narito ang isang halimbawa ng paggamit ng problema:

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

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

Mga default na setting

Maaari mong baguhin ang mga default na setting para sa isang plugin sa pamamagitan ng pagbabago sa Constructor.Defaultobject ng plugin:

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

Mga pamamaraan at katangian

Inilalantad ng bawat plugin ng Bootstrap ang mga sumusunod na pamamaraan at mga static na katangian.

Pamamaraan	Paglalarawan
`dispose`	Sinisira ang modal ng isang elemento. (Aalisin ang nakaimbak na data sa elemento ng DOM)
`getInstance`	Static na pamamaraan na nagbibigay-daan sa iyong makuha ang modal instance na nauugnay sa isang elemento ng DOM.
`getOrCreateInstance`	Static na paraan na nagbibigay-daan sa iyong makuha ang modal instance na nauugnay sa isang elemento ng DOM, o lumikha ng bago kung sakaling hindi ito nasimulan.

Static na ari-arian	Paglalarawan
`NAME`	Ibinabalik ang pangalan ng plugin. (Halimbawa: `bootstrap.Tooltip.NAME`)
`VERSION`	Maaaring ma-access ang bersyon ng bawat plugin ng Bootstrap sa pamamagitan ng pag- `VERSION`aari ng constructor ng plugin (Halimbawa: `bootstrap.Tooltip.VERSION`)

Sanitizer

Ginagamit ng Tooltips at Popovers ang aming built-in na sanitizer para i-sanitize ang mga opsyon na tumatanggap ng HTML.

Ang default allowListna halaga ay ang sumusunod:

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

Kung gusto mong magdagdag ng mga bagong value sa default na ito allowListmaaari mong gawin ang sumusunod:

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)

Kung gusto mong i-bypass ang aming sanitizer dahil mas gusto mong gumamit ng dedikadong library, halimbawa DOMPuify , dapat mong gawin ang sumusunod:

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

Opsyonal gamit ang jQuery

Hindi mo kailangan ang jQuery sa Bootstrap 5 , ngunit posible pa ring gamitin ang aming mga bahagi sa jQuery. Kung matukoy ng Bootstrap jQueryang windowbagay, idaragdag nito ang lahat ng aming mga bahagi sa sistema ng plugin ng jQuery. Ito ay nagpapahintulot sa iyo na gawin ang mga sumusunod:

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

Ang parehong napupunta para sa aming iba pang mga bahagi.

Walang conflict

Minsan kinakailangan na gumamit ng mga plugin ng Bootstrap kasama ng iba pang mga framework ng UI. Sa mga sitwasyong ito, maaaring mangyari paminsan-minsan ang mga banggaan ng namespace. Kung mangyari ito, maaari kang tumawag .noConflictsa plugin na nais mong ibalik ang halaga.

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

Hindi opisyal na sinusuportahan ng Bootstrap ang mga third-party na JavaScript library tulad ng Prototype o jQuery UI. Sa kabila .noConflictat namespaced na mga kaganapan, maaaring may mga problema sa compatibility na kailangan mong ayusin nang mag-isa.

mga kaganapan sa jQuery

Makikita ng Bootstrap ang jQuery kung jQuerynaroroon sa windowobject at walang data-bs-no-jqueryattribute na nakatakda sa <body>. Kung natagpuan ang jQuery, ang Bootstrap ay maglalabas ng mga kaganapan salamat sa sistema ng kaganapan ng jQuery. Kaya kung gusto mong makinig sa mga kaganapan ng Bootstrap, kakailanganin mong gamitin ang mga pamamaraan ng jQuery ( .on, .one) sa halip na addEventListener.

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

Naka-disable ang JavaScript

Walang espesyal na fallback ang mga plugin ng Bootstrap kapag hindi pinagana ang JavaScript. Kung nagmamalasakit ka sa karanasan ng user sa kasong ito, gamitin <noscript>upang ipaliwanag ang sitwasyon (at kung paano muling paganahin ang JavaScript) sa iyong mga user, at/o magdagdag ng sarili mong mga custom na fallback.