JavaScript

Оживіть Bootstrap за допомогою наших додаткових плагінів JavaScript. Дізнайтеся про кожен плагін, наші дані та параметри програмного API тощо.

На цій сторінці

Індивідуальний або складений

Плагіни можна включати окремо (за допомогою Bootstrap individual js/dist/*.js) або всі одночасно за допомогою bootstrap.jsабо мінімізованого bootstrap.min.js(не включайте обидва).

Якщо ви використовуєте збірник (Webpack, Parcel, Vite…), ви можете використовувати /js/dist/*.jsфайли, готові до UMD.

Використання з фреймворками JavaScript

Хоча CSS Bootstrap можна використовувати з будь-яким фреймворком, JavaScript Bootstrap не повністю сумісний із фреймворками 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 bundlers, використання 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 з іншими фреймворками інтерфейсу користувача. За таких обставин час від часу можуть виникати конфлікти простору імен. Якщо це станеться, ви можете викликати .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) своїм користувачам, і/або додайте власні запасні варіанти.