JavaScript

Gleymdu Bootstrap lífi með valfrjálsu JavaScript viðbótunum okkar. Lærðu um hverja viðbætur, gögn okkar og forritafræðilega API valkosti og fleira.

Á þessari síðu

Einstök eða samsett

Viðbætur geta verið innifalin fyrir sig (með því að nota Bootstrap's individual js/dist/*.js), eða öll í einu með því að nota bootstrap.jseða minnka bootstrap.min.js(ekki innihalda bæði).

Ef þú notar búntara (Webpack, Parcel, Vite…), geturðu notað /js/dist/*.jsskrár sem eru UMD tilbúnar.

Notkun með JavaScript ramma

Þó að hægt sé að nota Bootstrap CSS með hvaða ramma sem er, þá er Bootstrap JavaScript ekki fullkomlega samhæft við JavaScript ramma eins og React, Vue og Angular sem gera ráð fyrir fullri þekkingu á DOM. Bæði Bootstrap og ramminn gætu reynt að stökkbreyta sama DOM frumefninu, sem leiðir til galla eins og fellilista sem eru fastir í „opinni“ stöðu.

Betri valkostur fyrir þá sem nota þessa tegund ramma er að nota ramma-sérstakan pakka í stað Bootstrap JavaScript. Hér eru nokkrir af vinsælustu valkostunum:

React: React Bootstrap
Vue: BootstrapVue (styður aðeins Vue 2 og Bootstrap 4 eins og er)
Skyrt: ng-stígvél

Að nota Bootstrap sem einingu

Prófaðu það sjálfur! Sæktu frumkóðann og sýnishornið til að nota Bootstrap sem ES einingu úr twbs/examples geymslunni . Þú getur líka opnað dæmið í StackBlitz .

Við bjóðum upp á útgáfu af Bootstrap byggð sem ESM( bootstrap.esm.jsog bootstrap.esm.min.js) sem gerir þér kleift að nota Bootstrap sem einingu í vafranum, ef markvöfrarnir þínir styðja það .

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

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

Samanborið við JS búntara, að nota ESM í vafranum krefst þess að þú notir alla slóðina og skráarnafnið í stað einingarnafns. Lestu meira um JS einingar í vafranum. Þess vegna notum við 'bootstrap.esm.min.js'í staðinn fyrir 'bootstrap'ofan. Hins vegar er þetta enn flóknara vegna Popper háð okkar, sem flytur Popper inn í JavaScript okkar eins og svo:

import * as Popper from "@popperjs/core"

Ef þú reynir þetta eins og það er, muntu sjá villu í stjórnborðinu eins og eftirfarandi:

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

Til að laga þetta geturðu notað til importmapað leysa handahófskenndu einingaheitin til að klára slóðir. Ef markvöfrarnir þínir styðja ekki importmapþarftu að nota es-module-shims verkefnið. Svona virkar það fyrir Bootstrap og 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>

Ósjálfstæði

Sum viðbætur og CSS íhlutir eru háðir öðrum viðbótum. Ef þú lætur viðbætur fylgja með sér, vertu viss um að athuga hvort þessar ósjálfstæði séu í skjölunum.

Fellilistarnir okkar, sprettigluggar og verkfæraábendingar eru einnig háðar Popper .

Gagnaeiginleikar

Næstum allar Bootstrap viðbætur er hægt að virkja og stilla í gegnum HTML eingöngu með gagnaeiginleikum (valin leið okkar til að nota JavaScript virkni). Gakktu úr skugga um að þú notir aðeins eitt sett af gagnaeigindum á einum þætti (td þú getur ekki kveikt á tóli og aðferð frá sama hnappi).

Þar sem hægt er að senda valkosti í gegnum gagnaeiginleika eða JavaScript geturðu bætt valkostsheiti við data-bs-, eins og í data-bs-animation="{value}". Gakktu úr skugga um að breyta tilfelli tegundar valmöguleikans úr " camelCase " í " kebab-case " þegar þú sendir valkostina í gegnum gagnaeiginleika. Notaðu til dæmis data-bs-custom-class="beautifier"í staðinn fyrir data-bs-customClass="beautifier".

Frá og með Bootstrap 5.2.0 styðja allir íhlutir tilrauna frátekinn gagnaeiginleika data-bs-configsem getur hýst einfalda íhlutastillingu sem JSON streng. Þegar eining hefur data-bs-config='{"delay":0, "title":123}'og eiginleika verður data-bs-title="456"lokagildið og aðskildu gagnaeiginirnar munu hnekkja gildum sem gefin eru á . Að auki geta núverandi gagnaeiginleikar hýst JSON gildi eins og .title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Valsmenn

Við notum innfædda querySelectorog querySelectorAllaðferðir til að spyrjast fyrir um DOM þætti af frammistöðuástæðum, svo þú verður að nota gilda veljara . Ef þú notar sérstaka veljara eins og collapse:Example, vertu viss um að sleppa þeim.

Viðburðir

Bootstrap býður upp á sérsniðna atburði fyrir einstaka aðgerðir flestra viðbætur. Yfirleitt koma þær í óendanlegu formi og þátíð - þar sem óendanlegur (til dæmis show) er ræstur í upphafi atburðar, og þátíðarform hans (til dæmis shown) er ræst þegar aðgerð er lokið.

Allir óendanlegir atburðir veita preventDefault()virkni. Þetta veitir möguleika á að stöðva framkvæmd aðgerða áður en hún hefst. Ef þú skilar ósönnum frá atburðastjórnun mun einnig sjálfkrafa hringja preventDefault().

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

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

Forritað API

Allir smiðir samþykkja valfrjálsan valmöguleikahlut eða ekkert (sem ræsir viðbót með sjálfgefna hegðun sinni):

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

Ef þú vilt fá tiltekið viðbótatilvik, afhjúpar hvert viðbót getInstanceaðferð. Til dæmis, til að sækja tilvik beint úr frumefni:

bootstrap.Popover.getInstance(myPopoverEl)

Þessi aðferð mun koma aftur nullef tilvik er ekki sett af stað yfir umbeðinn þátt.

Að öðrum kosti er getOrCreateInstancehægt að nota til að fá tilvikið tengt við DOM frumefni, eða búa til nýtt ef það var ekki frumstillt.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Ef tilvik var ekki frumstillt, getur það samþykkt og notað valfrjálsan stillingarhlut sem önnur rök.

CSS veljarar í smiðjum

Til viðbótar við getInstanceog getOrCreateInstanceaðferðirnar geta allir viðbætisframleiðendur samþykkt DOM frumefni eða gilt CSS val sem fyrstu rök. Viðbætur eru að finna með querySelectoraðferðinni þar sem viðbætur okkar styðja aðeins einn þátt.

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

Ósamstilltur aðgerðir og umskipti

Allar forritunarfræðilegar API-aðferðir eru ósamstilltar og snúa aftur til þess sem hringir þegar umskiptin eru hafin, en áður en henni lýkur . Til að framkvæma aðgerð þegar umskiptum er lokið geturðu hlustað á samsvarandi atburði.

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

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

Að auki verður aðferðakall á umbreytingarhluta hunsað .

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`aðferð

Þó að það kann að virðast rétt að nota disposeaðferðina strax á eftir hide()mun það leiða til rangra niðurstaðna. Hér er dæmi um vandamálanotkun:

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

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

Sjálfgefnar stillingar

Þú getur breytt sjálfgefnum stillingum fyrir viðbót með því að breyta Constructor.Defaulthlut viðbótarinnar:

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

Aðferðir og eiginleikar

Sérhver Bootstrap tappi afhjúpar eftirfarandi aðferðir og truflanir eiginleika.

Aðferð	Lýsing
`dispose`	Eyðileggur form frumefnis. (Fjarlægir vistuð gögn á DOM-einingunni)
`getInstance`	Static aðferð sem gerir þér kleift að fá modal tilvikið tengt DOM frumefni.
`getOrCreateInstance`	Statísk aðferð sem gerir þér kleift að fá modal tilvikið tengt DOM frumefni, eða búa til nýjan ef það var ekki frumstillt.

Statísk eign	Lýsing
`NAME`	Skilar heiti viðbótarinnar. (Dæmi: `bootstrap.Tooltip.NAME`)
`VERSION`	Hægt er að nálgast útgáfuna af öllum Bootstrap viðbótunum í gegnum `VERSION`eign byggingaraðila viðbótarinnar (dæmi: `bootstrap.Tooltip.VERSION`)

Hreinsiefni

Tooltips og Popovers nota innbyggða sótthreinsiefnið okkar til að hreinsa valkosti sem samþykkja HTML.

Sjálfgefið allowListgildi er eftirfarandi:

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

Ef þú vilt bæta nýjum gildum við þetta sjálfgefið allowListgeturðu gert eftirfarandi:

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)

Ef þú vilt komast framhjá hreinsiefninu okkar vegna þess að þú vilt frekar nota sérstakt bókasafn, til dæmis DOMPurify , ættirðu að gera eftirfarandi:

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

Mögulega með því að nota jQuery

Þú þarft ekki jQuery í Bootstrap 5 , en það er samt hægt að nota íhlutina okkar með jQuery. Ef Bootstrap finnur jQueryí windowhlutnum mun það bæta við öllum íhlutum okkar í jQuery viðbótakerfinu. Þetta gerir þér kleift að gera eftirfarandi:

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

Sama gildir um aðra þætti okkar.

Engin átök

Stundum er nauðsynlegt að nota Bootstrap viðbætur með öðrum UI ramma. Við þessar aðstæður geta árekstrar í nafnrými átt sér stað einstaka sinnum. Ef þetta gerist geturðu hringt .noConflictí viðbótina sem þú vilt breyta gildinu á.

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

Bootstrap styður ekki opinberlega þriðja aðila JavaScript bókasöfn eins og Prototype eða jQuery UI. Þrátt fyrir .noConflictatburði með nafnabili geta komið upp samhæfnisvandamál sem þú þarft að laga á eigin spýtur.

jQuery viðburðir

Bootstrap mun greina jQuery ef það jQueryer til staðar í windowhlutnum og það er engin data-bs-no-jqueryeiginleiki stilltur á <body>. Ef jQuery finnst mun Bootstrap senda frá sér atburði þökk sé viðburðakerfi jQuery. Þannig að ef þú vilt hlusta á atburði Bootstrap þarftu að nota jQuery aðferðirnar ( .on, .one) í staðinn fyrir addEventListener.

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

Slökkt á JavaScript

Viðbætur Bootstrap hafa enga sérstaka frávik þegar JavaScript er óvirkt. Ef þér er annt um notendaupplifunina í þessu tilviki, notaðu <noscript>þá til að útskýra aðstæður (og hvernig á að virkja JavaScript aftur) fyrir notendum þínum og/eða bæta við eigin sérsniðnum fallbacks.