in English

JavaScript

Jepni Bootstrap në jetë me shtojcat tona opsionale JavaScript. Mësoni për çdo shtojcë, të dhënat tona dhe opsionet programatike API dhe më shumë.

Në këtë faqe

Individuale ose të përpiluara

Shtojcat mund të përfshihen individualisht (duke përdorur individualin e Bootstrap js/dist/*.js), ose të gjitha menjëherë duke përdorur bootstrap.jsose të minuar bootstrap.min.js(mos i përfshini të dyja).

Nëse përdorni një bundler (Webpack, Parcel, Vite…), ju mund të përdorni /js/dist/*.jsskedarë që janë gati UMD.

Përdorimi me kornizat JavaScript

Ndërsa Bootstrap CSS mund të përdoret me çdo kornizë, Bootstrap JavaScript nuk është plotësisht i pajtueshëm me kornizat JavaScript si React, Vue dhe Angular të cilat supozojnë njohuri të plotë të DOM. Si Bootstrap ashtu edhe korniza mund të përpiqen të ndryshojnë të njëjtin element DOM, duke rezultuar në gabime si pikat e lëshimit që janë ngecur në pozicionin "hapur".

Një alternativë më e mirë për ata që përdorin këtë lloj kornizash është përdorimi i një pakete specifike të kornizës në vend të Bootstrap JavaScript. Këtu janë disa nga opsionet më të njohura:

Reagon: React Bootstrap
Vue: BootstrapVue (aktualisht mbështet vetëm Vue 2 dhe Bootstrap 4)
Këndore: ng-bootstrap

Përdorimi i Bootstrap si modul

Provojeni vetë! Shkarkoni kodin burimor dhe demonstrimin e punës për përdorimin e Bootstrap si një modul ES nga depoja e twbs/shembujve . Ju gjithashtu mund ta hapni shembullin në StackBlitz .

Ne ofrojmë një version të Bootstrap të ndërtuar si ESM( bootstrap.esm.jsdhe bootstrap.esm.min.js) i cili ju lejon të përdorni Bootstrap si një modul në shfletues, nëse shfletuesit tuaj të synuar e mbështesin atë .

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

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

Krahasuar me grupet JS, përdorimi i ESM në shfletues kërkon që ju të përdorni shtegun e plotë dhe emrin e skedarit në vend të emrit të modulit. Lexoni më shumë rreth moduleve JS në shfletues. Kjo është arsyeja pse ne përdorim 'bootstrap.esm.min.js'në vend të 'bootstrap'mësipërm. Sidoqoftë, kjo ndërlikohet më tej nga varësia jonë nga Popper, e cila importon Popper në JavaScript tonë si kjo:

import * as Popper from "@popperjs/core"

Nëse e provoni këtë siç është, do të shihni një gabim në tastierë si më poshtë:

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

Për ta rregulluar këtë, mund të përdorni një importmappër të zgjidhur emrat arbitrar të moduleve për të përfunduar shtigjet. Nëse shfletuesit tuaj të synuar nuk e mbështesin importmap, do t'ju duhet të përdorni projektin es-module-shims . Ja se si funksionon për Bootstrap dhe 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>

varësitë

Disa shtojca dhe komponentë CSS varen nga shtojcat e tjera. Nëse përfshini shtojcat individualisht, sigurohuni që të kontrolloni për këto varësi në dokumente.

Zbritja, popover-et dhe këshillat tona të veglave varen gjithashtu nga Popper .

Atributet e të dhënave

Pothuajse të gjitha shtojcat e Bootstrap mund të aktivizohen dhe konfigurohen vetëm përmes HTML me atributet e të dhënave (mënyra jonë e preferuar për të përdorur funksionalitetin JavaScript). Sigurohuni që të përdorni vetëm një grup atributesh të dhënash në një element të vetëm (p.sh., nuk mund të aktivizoni një këshillë mjeti dhe modal nga i njëjti buton.)

Meqenëse opsionet mund të kalohen nëpërmjet atributeve të të dhënave ose JavaScript, ju mund të shtoni një emër opsioni në data-bs-, si në data-bs-animation="{value}". Sigurohuni që të ndryshoni llojin e rastit të emrit të opsionit nga “ CamelCase ” në “ kebab-case ” kur kaloni opsionet përmes atributeve të të dhënave. Për shembull, përdorni data-bs-custom-class="beautifier"në vend të data-bs-customClass="beautifier".

Që nga Bootstrap 5.2.0, të gjithë komponentët mbështesin një atribut eksperimental të të dhënave të rezervuara data-bs-configqë mund të vendosë konfigurimin e thjeshtë të komponentit si një varg JSON. Kur një element ka data-bs-config='{"delay":0, "title":123}'dhe data-bs-title="456"atribute, titlevlera përfundimtare do të jetë 456dhe atributet e veçanta të të dhënave do të zëvendësojnë vlerat e dhëna në data-bs-config. Përveç kësaj, atributet ekzistuese të të dhënave janë në gjendje të strehojnë vlera JSON si data-bs-delay='{"show":0,"hide":150}'.

Përzgjedhës

Ne përdorim bazën querySelectordhe querySelectorAllmetodat për të kërkuar elementë DOM për arsye të performancës, kështu që ju duhet të përdorni përzgjedhës të vlefshëm . Nëse përdorni përzgjedhës të veçantë si collapse:Example, sigurohuni që t'i shmangni ato.

Ngjarjet

Bootstrap ofron ngjarje të personalizuara për shumicën e veprimeve unike të shtojcave. Në përgjithësi, këto vijnë në një formë të paskajores dhe të paskajores - ku infinitivi (sh. show) shkaktohet në fillim të një ngjarjeje, dhe forma e tij e paskajores (p.sh. ) shownnxitet në përfundimin e një veprimi.

Të gjitha ngjarjet infinitive ofrojnë preventDefault()funksionalitet. Kjo siguron mundësinë për të ndaluar ekzekutimin e një veprimi përpara se të fillojë. Kthimi i "false" nga një mbajtës i ngjarjeve do të telefonojë gjithashtu automatikisht preventDefault().

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

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

API programatike

Të gjithë konstruktorët pranojnë një objekt opsionesh opsionale ose asgjë (që fillon një shtojcë me sjelljen e tij të paracaktuar):

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

Nëse dëshironi të merrni një shembull të veçantë të shtojcës, secila shtojcë ekspozon një getInstancemetodë. Për shembull, për të marrë një shembull direkt nga një element:

bootstrap.Popover.getInstance(myPopoverEl)

Kjo metodë do të kthehet nullnëse një shembull nuk inicohet mbi elementin e kërkuar.

Përndryshe, getOrCreateInstancemund të përdoret për të marrë shembullin e lidhur me një element DOM, ose për të krijuar një të ri në rast se nuk është inicializuar.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Në rast se një shembull nuk është inicializuar, ai mund të pranojë dhe të përdorë një objekt konfigurimi opsional si argument të dytë.

Përzgjedhës CSS në konstruktorë

Përveç metodave getInstancedhe getOrCreateInstance, të gjithë ndërtuesit e shtojcave mund të pranojnë një element DOM ose një përzgjedhës të vlefshëm CSS si argumentin e parë. Elementet e shtojcave gjenden me querySelectormetodën pasi shtojcat tona mbështesin vetëm një element të vetëm.

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

Funksionet dhe tranzicionet asinkrone

Të gjitha metodat programatike API janë asinkrone dhe kthehen te thirrësi pasi të fillojë tranzicioni, por përpara se të përfundojë . Për të ekzekutuar një veprim pasi të ketë përfunduar tranzicioni, mund të dëgjoni ngjarjen përkatëse.

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

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

Përveç kësaj, një thirrje metodë në një komponent në tranzicion do të injorohet .

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`metodë

Megjithëse mund të duket e saktë të përdoret disposemetoda menjëherë pas hide(), kjo do të çojë në rezultate të pasakta. Këtu është një shembull i përdorimit të problemit:

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

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

Cilësimet e parazgjedhura

Ju mund të ndryshoni cilësimet e paracaktuara për një shtesë duke modifikuar Constructor.Defaultobjektin e shtojcës:

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

Metodat dhe vetitë

Çdo shtojcë Bootstrap ekspozon metodat dhe vetitë statike të mëposhtme.

Metoda	Përshkrim
`dispose`	Shkatërron modalitetin e një elementi. (Heq të dhënat e ruajtura në elementin DOM)
`getInstance`	Metoda statike e cila ju lejon të merrni shembullin modal të lidhur me një element DOM.
`getOrCreateInstance`	Metoda statike e cila ju lejon të merrni shembullin modal të lidhur me një element DOM, ose të krijoni një të ri në rast se nuk ishte inicializuar.

Veti statike	Përshkrim
`NAME`	Kthen emrin e shtojcës. (Shembull: `bootstrap.Tooltip.NAME`)
`VERSION`	Versioni i secilës prej shtojcave të Bootstrap mund të aksesohet nëpërmjet `VERSION`vetive të konstruktorit të shtojcave (Shembull: `bootstrap.Tooltip.VERSION`)

Dezinfektues

Këshillat e veglave dhe Popover-at përdorin dezinfektuesin tonë të integruar për të dezinfektuar opsionet që pranojnë HTML.

Vlera e paracaktuar allowListështë si më poshtë:

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

Nëse dëshironi të shtoni vlera të reja në këtë parazgjedhje allowList, mund të bëni sa më poshtë:

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)

Nëse dëshironi të anashkaloni dezinfektuesin tonë sepse preferoni të përdorni një bibliotekë të dedikuar, për shembull DOMPurify , duhet të bëni sa më poshtë:

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

Opsionale duke përdorur jQuery

Ju nuk keni nevojë për jQuery në Bootstrap 5 , por është ende e mundur të përdorni komponentët tanë me jQuery. Nëse Bootstrap zbulon jQuerynë windowobjekt, ai do të shtojë të gjithë komponentët tanë në sistemin e shtojcave të jQuery. Kjo ju lejon të bëni sa më poshtë:

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

E njëjta gjë vlen edhe për komponentët tanë të tjerë.

Asnjë konflikt

Ndonjëherë është e nevojshme të përdoren shtojcat Bootstrap me korniza të tjera UI. Në këto rrethana, herë pas here mund të ndodhin përplasje të hapësirës së emrave. Nëse kjo ndodh, mund të telefononi .noConflictshtojcën që dëshironi të ktheni vlerën.

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

Bootstrap nuk mbështet zyrtarisht bibliotekat JavaScript të palëve të treta si UI Prototype ose jQuery. Pavarësisht .noConflictdhe ngjarjeve me hapësirë emri, mund të ketë probleme të përputhshmërisë që duhet t'i rregulloni vetë.

Ngjarjet jQuery

Bootstrap do të zbulojë jQuery nëse jQueryështë i pranishëm në windowobjekt dhe nuk ka asnjë data-bs-no-jqueryatribut të vendosur në <body>. Nëse gjendet jQuery, Bootstrap do të emetojë ngjarje falë sistemit të ngjarjeve të jQuery. Pra, nëse doni të dëgjoni ngjarjet e Bootstrap, do të duhet të përdorni metodat jQuery ( .on, .one) në vend të addEventListener.

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

JavaScript i çaktivizuar

Shtojcat e Bootstrap nuk kanë kthim të veçantë kur JavaScript është i çaktivizuar. Nëse ju intereson përvoja e përdoruesit në këtë rast, përdorni <noscript>për të shpjeguar situatën (dhe si të riaktivizoni JavaScript) përdoruesve tuaj dhe/ose shtoni kthimet tuaja të personalizuara.