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

Попробуйте сами! Скачайте исходный код и рабочее демо для использования Bootstrap с React, Next.js и React Bootstrap из репозитория twbs/examples. Вы также можете открыть пример в StackBlitz.
Vue: BootstrapVue (Bootstrap 4)
Vue 3: BootstrapVueNext (Bootstrap 5, в настоящее время в альфа-версии)
Angular: ng-bootstrap or ngx-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' выше. Однако это еще более усложняется нашей зависимостью от 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/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" 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/core@2.11.8/dist/esm/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/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}'.

Окончательный объект конфигурации — это объединенный результат data-bs-config, data-bs- и js object, где последний заданный ключ-значение переопределяет другие.

Селекторы

Мы используем стандартные методы querySelector и querySelectorAll для запроса DOM-элементов по соображениям производительности, поэтому вы должны использовать допустимые селекторы. Если вы используете специальные селекторы, такие как collapse:Example, обязательно экранируйте их.

События

Bootstrap предоставляет пользовательские события для большинства уникальных действий плагинов. Обычно они представлены в форме инфинитива и причастия прошедшего времени — где инфинитив (например, show) срабатывает в начале события, а его форма причастия прошедшего времени (например, shown) срабатывает при завершении действия.

Все события в форме инфинитива предоставляют функциональность preventDefault(). Это обеспечивает возможность остановить выполнение действия до его начала. Возвращение false из обработчика событий также автоматически вызовет preventDefault().

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

myModal.addEventListener('show.bs.modal', event => {
  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 на странице, если они настроены соответствующим образом. Для предотвращения атак межсайтового скриптинга (XSS) эти компоненты используют наш встроенный санитайзер контента для очистки любых опций, которые принимают HTML, перед их отображением на странице. Очистка контента включена по умолчанию.

Теги и атрибуты, разрешенные по умолчанию, приведены ниже. Любые теги или атрибуты, не явно разрешенные, будут удалены во время очистки:

js/src/util/sanitizer.js

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i

export 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: [],
  dd: [],
  div: [],
  dl: [],
  dt: [],
  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: []
}

Проявляйте осторожность при использовании этих расширенных опций. Обратитесь к Шпаргалке OWASP по предотвращению межсайтового скриптинга для получения дополнительной информации. Уязвимости, вызванные исключительно отключением или изменением очистки контента, не считаются входящими в область модели безопасности Bootstrap.

Вы можете добавить новые значения в этот 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. Это позволяет вам делать следующее:

// to enable tooltips with the default configuration
$('[data-bs-toggle="tooltip"]').tooltip()

// to initialize tooltips with given configuration
$('[data-bs-toggle="tooltip"]').tooltip({
  boundary: 'clippingParents',
  customClass: 'myClass'
})

// to trigger the `show` method
$('#myTooltip').tooltip('show')

То же самое относится к нашим другим компонентам.

Отсутствие конфликтов

Иногда необходимо использовать плагины 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 и на <body> не установлен атрибут data-bs-no-jquery. Если jQuery обнаружен, Bootstrap будет генерировать события благодаря системе событий jQuery. Поэтому, если вы хотите прослушивать события Bootstrap, вам придется использовать методы jQuery (.on, .one) вместо addEventListener.

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

Отключенный JavaScript

Плагины Bootstrap не имеют особого резервного варианта, когда JavaScript отключен. Если вас волнует пользовательский опыт в этом случае, используйте <noscript>, чтобы объяснить ситуацию (и как повторно включить JavaScript) вашим пользователям и/или добавьте собственные пользовательские резервные варианты.