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)
Angular: 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 bundler-ите, използването на ESM в браузъра изисква да използвате пълния път и име на файла вместо името на модула. Прочетете повече за JS модулите в браузъра. Ето защо използваме 'bootstrap.esm.min.js'вместо по 'bootstrap'-горе. Това обаче е допълнително усложнено от нашата зависимост от Popper, която импортира Popper в нашия 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 ” на „ kebab-case ”, когато предавате опциите чрез атрибути на данни. Например използвайте 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 с други UI рамки. При тези обстоятелства понякога могат да възникнат сблъсъци в пространството на имена. Ако това се случи, можете да извикате .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) на вашите потребители и/или добавете свои собствени персонализирани резервни варианти.