Bootstrap 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

Использование 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/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" 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.2/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

Все конструкторы принимают необязательный объект options или ничего (который запускает плагин с его поведением по умолчанию):

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

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: [],
  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. Это позволяет вам выполнить следующее:

// 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 с другими фреймворками пользовательского интерфейса. В таких обстоятельствах иногда могут возникать коллизии пространств имен. Если это произойдет, вы можете вызвать .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) своим пользователям и / или добавить свои собственные резервные варианты.

На этой странице