JavaScript

Оживејте го Bootstrap со нашите опционални приклучоци за JavaScript. Дознајте за секој додаток, нашите податоци и програмски опции за API и повеќе.

На оваа страница

Индивидуални или составени

Приклучоците може да се вклучат поединечно (со користење на поединецот на Bootstrap js/dist/*.js), или сите одеднаш користејќи bootstrap.jsили минимизирани bootstrap.min.js(не ги вклучувајте и двете).

Ако користите пакет (Webpack, Parcel, Vite…), можете да користите /js/dist/*.jsдатотеки што се подготвени за UMD.

Употреба со JavaScript рамки

Додека Bootstrap CSS може да се користи со која било рамка, Bootstrap JavaScript не е целосно компатибилен со JavaScript рамки како React, Vue и Angular кои претпоставуваат целосно познавање на DOM. И Bootstrap и рамката може да се обидат да го мутираат истиот DOM елемент, што ќе резултира со грешки како што се паѓачките мени кои се заглавени во „отворена“ позиција.

Подобра алтернатива за оние кои користат ваков тип рамки е да користат пакет специфичен за рамка наместо Bootstrap JavaScript. Еве некои од најпопуларните опции:

React: React Bootstrap
Vue: BootstrapVue (во моментов поддржува само Vue 2 и Bootstrap 4)
Аголна: ng-bootstrap

Користење на Bootstrap како модул

Пробајте го сами! Преземете го изворниот код и работната демо за користење на Bootstrap како ES модул од складиштето twbs/examples . Можете исто така да го отворите примерот во StackBlitz .

Обезбедуваме верзија на Bootstrap изградена како ESM( bootstrap.esm.jsи bootstrap.esm.min.js) која ви овозможува да го користите Bootstrap како модул во прелистувачот, доколку вашите насочени прелистувачи го поддржуваат .

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

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

Во споредба со пакетите JS, користењето на ESM во прелистувачот бара да ја користите целосната патека и името на датотеката наместо името на модулот. Прочитајте повеќе за JS модулите во прелистувачот. Затоа користиме 'bootstrap.esm.min.js'наместо 'bootstrap'погоре. Сепак, ова е дополнително комплицирано од нашата зависност од Попер, која го увезува Попер во нашиот JavaScript вака:

import * as Popper from "@popperjs/core"

Ако го пробате ова како што е, ќе видите грешка во конзолата како што следува:

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

За да го поправите ова, можете да користите за importmapда ги решите произволните имиња на модулите за да ги комплетирате патеките. Ако вашите насочени прелистувачи не поддржуваат importmap, ќе треба да го користите проектот es-module-shims . Еве како работи за Bootstrap и 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>

Зависности

Некои приклучоци и CSS компоненти зависат од други приклучоци. Ако вклучите додатоци поединечно, проверете дали ги имате овие зависности во документите.

Нашите спуштања, поповери и совети за алатки исто така зависат од Popper .

Атрибути на податоци

Речиси сите приклучоци за Bootstrap можат да се овозможат и конфигурираат само преку HTML со атрибути на податоци (нашиот претпочитан начин за користење на JavaScript функционалноста). Погрижете се да користите само еден сет на атрибути на податоци на еден елемент (на пр., не можете да активирате совет за алатка и модал од истото копче.)

Бидејќи опциите може да се пренесат преку атрибути на податоци или JavaScript, можете да додадете име на опција на data-bs-, како во data-bs-animation="{value}". Погрижете се да го смените типот на футролата на името на опцијата од „ camelCase “ во „ ќебап-футрола “ кога ги пренесувате опциите преку атрибути на податоци. На пример, користете data-bs-custom-class="beautifier"наместо data-bs-customClass="beautifier".

Почнувајќи од Bootstrap 5.2.0, сите компоненти поддржуваат експериментален атрибут за резервирани податоци data-bs-configшто може да содржи едноставна конфигурација на компоненти како низа JSON. Кога елементот има data-bs-config='{"delay":0, "title":123}'и data-bs-title="456"атрибути, конечната titleвредност ќе биде 456и посебните атрибути на податоци ќе ги отфрлат вредностите дадени на data-bs-config. Покрај тоа, постоечките атрибути на податоци можат да ги сместат вредностите на JSON како data-bs-delay='{"show":0,"hide":150}'.

Селектори

Ги користиме природните querySelectorи querySelectorAllметодите за да побараме елементи на DOM поради перформанси, па затоа мора да користите валидни селектори . Ако користите специјални селектори како collapse:Example, не заборавајте да ги избегнете.

Настани

Bootstrap обезбедува сопствени настани за уникатните дејства на повеќето приклучоци. Општо земено, овие доаѓаат во форма на инфинитив и минато партицип - каде што инфинитивот (пр. show) се активира на почетокот на настанот, а неговата форма на минато партицип (пр. shown) се активира при завршување на дејството.

Сите инфинитивни настани обезбедуваат preventDefault()функционалност. Ова обезбедува можност да се запре извршувањето на дејството пред да започне. Враќањето на false од управувачот на настани исто така автоматски ќе се јави preventDefault().

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

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

Програмски API

Сите конструктори прифаќаат изборен објект со опции или ништо (што иницира додаток со неговото стандардно однесување):

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

Ако сакате да добиете одреден пример на приклучок, секој приклучок изложува getInstanceметод. На пример, за да преземете пример директно од елемент:

bootstrap.Popover.getInstance(myPopoverEl)

Овој метод ќе се врати nullако не се иницира пример преку бараниот елемент.

Алтернативно, getOrCreateInstanceможе да се користи за да се добие примерокот поврзан со елемент DOM или да се создаде нов во случај да не е иницијализиран.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Во случај некој пример да не е иницијализиран, тој може да прифати и користи опционален конфигурациски објект како втор аргумент.

CSS селектори во конструктори

Покрај методите getInstanceи getOrCreateInstance, сите конструктори на приклучоци можат да прифатат елемент DOM или валиден CSS избирач како прв аргумент. Елементите на приклучокот се наоѓаат со querySelectorметодот бидејќи нашите приклучоци поддржуваат само еден елемент.

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

Асинхрони функции и транзиции

Сите програмски методи на API се асинхрони и се враќаат кај повикувачот штом ќе започне транзицијата, но пред да заврши . За да извршите дејство откако ќе заврши транзицијата, можете да го слушате соодветниот настан.

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

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

Дополнително, повик на метод на компонента во транзиција ќе се игнорира .

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`метод

Иако може да изгледа правилно да се користи disposeметодот веднаш по hide(), тоа ќе доведе до неточни резултати. Еве пример за употреба на проблемот:

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

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

Стандардни поставки

Можете да ги промените стандардните поставки за приклучок со менување на Constructor.Defaultобјектот на приклучокот:

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

Методи и својства

Секој приклучок за Bootstrap ги изложува следните методи и статички својства.

Метод	Опис
`dispose`	Уништува модал на елемент. (Ги отстранува зачуваните податоци на елементот DOM)
`getInstance`	Статички метод кој ви овозможува да ја добиете модалната инстанца поврзана со елементот DOM.
`getOrCreateInstance`	Статички метод кој ви овозможува да ја добиете модалната инстанца поврзана со елементот DOM или да креирате нова во случај да не е иницијализирана.

Статично својство	Опис
`NAME`	Го враќа името на приклучокот. (Пример: `bootstrap.Tooltip.NAME`)
`VERSION`	До верзијата на секој од приклучоците на Bootstrap може да се пристапи преку `VERSION`својството на конструкторот на приклучокот (Пример: `bootstrap.Tooltip.VERSION`)

Средство за дезинфекција

Советите за алатки и поповерите го користат нашиот вграден дезинфекција за дезинфицирање на опциите што прифаќаат HTML.

Стандардната allowListвредност е следна:

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

Ако сакате да додадете нови вредности на овој стандард allowList, можете да го направите следново:

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)

Ако сакате да го заобиколите нашето средство за дезинфекција затоа што претпочитате да користите посветена библиотека, на пример DOMPurify , треба да го направите следново:

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

Изборно користење jQuery

Не ви треба jQuery во Bootstrap 5 , но сепак е можно да ги користите нашите компоненти со jQuery. Ако Bootstrap открие jQueryво windowобјектот, ќе ги додаде сите наши компоненти во системот за приклучоци на jQuery. Ова ви овозможува да го направите следново:

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

Истото важи и за нашите други компоненти.

Без конфликт

Понекогаш е неопходно да се користат приклучоци за Bootstrap со други рамки за интерфејс. Во овие околности, повремено може да се појават судири на именскиот простор. Ако тоа се случи, можете да го повикате .noConflictприклучокот на кој сакате да ја вратите вредноста.

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

Bootstrap официјално не поддржува JavaScript библиотеки од трета страна, како што се Prototype или jQuery UI. И покрај .noConflictнастаните со именски простор, може да има проблеми со компатибилноста што треба да ги поправите сами.

jQuery настани

Bootstrap ќе открие jQuery ако jQueryе присутен во windowобјектот и ако нема data-bs-no-jqueryпоставено атрибут на <body>. Ако се најде jQuery, Bootstrap ќе емитува настани благодарение на системот за настани на jQuery. Значи, ако сакате да ги слушате настаните на Bootstrap, ќе мора да ги користите методите jQuery ( .on, .one) наместо addEventListener.

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

Оневозможен JavaScript

Приклучоците на Bootstrap немаат посебна резервна копија кога JavaScript е оневозможен. Ако ви е гајле за корисничкото искуство во овој случај, користете <noscript>го за да им ја објасните ситуацијата (и како повторно да овозможите JavaScript) на вашите корисници и/или да додадете свои сопствени резервни верзии.