Mine põhisisu juurde Jätke dokumentide navigeerimise juurde
Check
in English

JavaScript

Äratage Bootstrap ellu meie valikuliste JavaScripti pistikprogrammidega. Lisateave iga pistikprogrammi, meie andmete ja programmilise API valikute ning muu kohta.

Sellel lehel

Individuaalne või koostatud

Pluginad saab lisada üksikult (kasutades Bootstrapi individuaalset funktsiooni js/dist/*.js) või kõik korraga, kasutades bootstrap.jsvõi minimeeritud bootstrap.min.js(ärge kaasake mõlemat).

Kui kasutate komplekteerijat (Webpack, Pack, Vite jne), saate kasutada /js/dist/*.jsfaile, mis on UMD-valmidusega.

Kasutamine JavaScripti raamistikega

Kuigi Bootstrap CSS-i saab kasutada mis tahes raamistikuga, ei ühildu Bootstrap JavaScript täielikult JavaScripti raamistikega, nagu React, Vue ja Angular, mis eeldavad täielikke teadmisi DOM-i kohta. Nii Bootstrap kui ka raamistik võivad üritada muteerida sama DOM-i elementi, mille tulemuseks on vead, näiteks rippmenüüd, mis on kinni jäänud asendisse "avatud".

Parem alternatiiv seda tüüpi raamistike kasutajatele on kasutada Bootstrap JavaScripti asemel raamistikupõhist paketti. Siin on mõned kõige populaarsemad valikud.

Bootstrapi kasutamine moodulina

Proovi ise! Laadige twbs/examples hoidlast alla lähtekood ja töötav demo Bootstrapi kasutamiseks ES-moodulina . Näite saate avada ka StackBlitzis .

Pakume Bootstrapi versiooni, mis on ehitatud kui ESM( bootstrap.esm.jsja bootstrap.esm.min.js), mis võimaldab teil kasutada Bootstrapi brauseris moodulina, kui teie sihitud brauserid seda toetavad .

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

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

Võrreldes JS-i komplekteerijatega nõuab ESM-i kasutamine brauseris mooduli nime asemel täieliku tee ja failinime kasutamist. Loe lähemalt JS-moodulite kohta brauseris. Sellepärast kasutame ülaltoodud 'bootstrap.esm.min.js'asemel . 'bootstrap'Kuid selle muudab veelgi keerulisemaks meie Popperi sõltuvus, mis impordib Popperi meie JavaScripti järgmiselt:

import * as Popper from "@popperjs/core"

Kui proovite seda praegusel kujul, näete konsoolis järgmist tõrget:

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

Selle parandamiseks saate kasutada importmapsuvaliste moodulite nimede lahendamiseks teede lõpuleviimiseks. Kui teie sihitud brauserid ei toeta importmap, peate kasutama projekti es-module-shims . Bootstrapi ja Popperi puhul toimib see järgmiselt.

<!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>

Sõltuvused

Mõned pistikprogrammid ja CSS-i komponendid sõltuvad teistest pistikprogrammidest. Kui lisate pistikprogrammid eraldi, kontrollige kindlasti nende sõltuvuste olemasolu dokumentidest.

Popperist sõltuvad ka meie rippmenüüd, hüpikaknad ja vihjed .

Andmete atribuudid

Peaaegu kõiki Bootstrapi pistikprogramme saab lubada ja konfigureerida ainult HTML-i kaudu koos andmeatribuutidega (meie eelistatud viis JavaScripti funktsiooni kasutamiseks). Kasutage ühel elemendil kindlasti ainult ühte andmeatribuutide komplekti (nt te ei saa samal nupul käivitada kohtspikri ja modaali).

Kuna suvandeid saab edastada andmeatribuutide või JavaScripti kaudu, saate valikule lisada valiku nime data-bs-, nagu näiteks data-bs-animation="{value}". Suvandite andmeatribuutide kaudu edastamisel muutke suvandi nime tõuketüüp „ camelCase ” asemel „ kebab-case ”. Näiteks data-bs-custom-class="beautifier"kasutage data-bs-customClass="beautifier".

Alates versioonist Bootstrap 5.2.0 toetavad kõik komponendid eksperimentaalset reserveeritud andmeatribuuti data-bs-config, mis mahutab lihtsa komponendi konfiguratsiooni JSON-stringina. Kui elemendil on atribuudid data-bs-config='{"delay":0, "title":123}'ja data-bs-title="456", on lõplik titleväärtus 456ja eraldi andmeatribuudid alistavad väärtused, mis on antud kuupäeval data-bs-config. Lisaks võivad olemasolevad andmeatribuudid sisaldada JSON-i väärtusi, nagu data-bs-delay='{"show":0,"hide":150}'.

Valijad

Kasutame DOM-i elementide päringute tegemiseks toimivuse huvides natiivset querySelectorja querySelectorAllmeetodeid, seega peate kasutama kehtivaid selektoreid . Kui kasutate spetsiaalseid valijaid, nagu collapse:Example, vältige neid kindlasti.

Sündmused

Bootstrap pakub kohandatud sündmusi enamiku pistikprogrammide ainulaadsete toimingute jaoks. Üldjuhul on need infinitiivi ja mineviku osastava vormina – kus infinitiiv (nt show) käivitatakse sündmuse alguses ja selle mineviku osastava vorm (nt shown) käivitatakse tegevuse lõppedes.

Kõik infinitiivsed sündmused pakuvad preventDefault()funktsionaalsust. See annab võimaluse toimingu sooritamine enne selle algust peatada. Sündmuste töötlejalt vale tagastamine kutsub automaatselt välja ka preventDefault().

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

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

Programmaatiline API

Kõik konstruktorid aktsepteerivad valikuliste suvandite objekti või mitte midagi (mis käivitab pistikprogrammi vaikekäitumisega):

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

Kui soovite hankida konkreetse pistikprogrammi eksemplari, avaldab iga pistikprogramm getInstancemeetodi. Näiteks eksemplari toomiseks otse elemendist:

bootstrap.Popover.getInstance(myPopoverEl)

See meetod naaseb, nullkui eksemplari ei algatata taotletud elemendi kaudu.

Teise võimalusena getOrCreateInstancesaab seda kasutada eksemplari seostamiseks DOM-i elemendiga või uue loomiseks juhuks, kui seda ei lähtestatud.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Kui eksemplari ei lähtestatud, võib see aktsepteerida ja kasutada teise argumendina valikulist konfiguratsiooniobjekti.

CSS-i valijad konstruktorites

Lisaks meetoditele getInstanceja saavad kõik pistikprogrammide konstruktorid esimese argumendina getOrCreateInstanceaktsepteerida DOM-i elementi või kehtivat CSS-i valijat . Plugina elemendid leitakse selle querySelectormeetodiga, kuna meie pistikprogrammid toetavad ainult ühte elementi.

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

Asünkroonsed funktsioonid ja üleminekud

Kõik programmilised API meetodid on asünkroonsed ja naasevad helistaja juurde pärast ülemineku algust, kuid enne selle lõppu . Toimingu sooritamiseks pärast ülemineku lõppemist saate kuulata vastavat sündmust.

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

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

Lisaks ignoreeritakse üleminekukomponendi meetodikutset .

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 !!

disposemeetod

Kuigi võib tunduda õige disposemeetodi kasutamine kohe pärast hide(), viib see valede tulemusteni. Siin on näide probleemi kasutamisest:

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

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

Vaikeseaded

Saate muuta pistikprogrammi vaikesätteid, muutes pistikprogrammi Constructor.Defaultobjekti.

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

Meetodid ja omadused

Iga Bootstrapi pistikprogramm paljastab järgmised meetodid ja staatilised omadused.

meetod Kirjeldus
dispose Hävitab elemendi modaali. (Eemaldab DOM-elemendile salvestatud andmed)
getInstance Staatiline meetod, mis võimaldab teil saada DOM-i elemendiga seotud modaalse eksemplari.
getOrCreateInstance Staatiline meetod, mis võimaldab teil saada DOM-i elemendiga seotud modaalse eksemplari või luua uue, kui seda ei lähtestatud.
Staatiline omadus Kirjeldus
NAME Tagastab pistikprogrammi nime. (Näide bootstrap.Tooltip.NAME:)
VERSION Iga Bootstrapi pistikprogrammi versioonile pääseb juurde VERSIONpistikprogrammi konstruktori atribuudi kaudu (näide: bootstrap.Tooltip.VERSION)

Puhastusvahend

Tööriistavihjed ja hüpikaknad kasutavad HTML-i aktsepteerivate valikute puhastamiseks meie sisseehitatud puhastusvahendit.

Vaikeväärtus allowListon järgmine:

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

Kui soovite sellele vaikeväärtusele lisada uusi väärtusi, allowListsaate teha järgmist.

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)

Kui soovite meie desinfitseerimisvahendist mööda minna, kuna eelistate kasutada spetsiaalset teeki, näiteks DOMpurify , peaksite tegema järgmist.

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

Soovi korral jQuery kasutamine

Te ei vaja Bootstrap 5-s jQueryt , kuid meie komponente on siiski võimalik jQueryga kasutada. Kui Bootstrap tuvastab objektis, jQuerylisab windowsee kõik meie komponendid jQuery pistikprogrammide süsteemi. See võimaldab teil teha järgmist.

$('[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 kehtib ka meie teiste komponentide kohta.

Ei mingit konflikti

Mõnikord on vaja Bootstrapi pistikprogramme kasutada koos teiste kasutajaliidese raamistikega. Sellistel juhtudel võib aeg-ajalt tekkida nimeruumi kokkupõrkeid. Kui see juhtub, võite helistada .noConflictpistikprogrammile, mille väärtust soovite taastada.

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

Bootstrap ei toeta ametlikult kolmandate osapoolte JavaScripti teeke, nagu Prototype või jQuery kasutajaliides. Vaatamata .noConflictja nimeruumiga sündmustele võib esineda ühilduvusprobleeme, mille peate ise lahendama.

jQuery sündmused

Bootstrap tuvastab jQuery, kui jQuerysee on windowobjektis olemas ja data-bs-no-jqueryatribuuti pole määratud <body>. Kui jQuery leitakse, väljastab Bootstrap sündmusi tänu jQuery sündmuste süsteemile. Nii et kui soovite kuulata Bootstrapi sündmusi, peate meetodi asemel kasutama jQuery meetodeid ( .on, ) ..oneaddEventListener

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

JavaScript on keelatud

Kui JavaScript on keelatud, pole Bootstrapi pistikprogrammidel erilist tagavara. Kui teile huvitab sel juhul kasutajakogemus, kasutage <noscript>olukorra selgitamiseks (ja JavaScripti uuesti lubamiseks) oma kasutajatele ja/või oma kohandatud varude lisamiseks.