JavaScript

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

Индивидуальный или скомпилированный

Плагины могут быть включены индивидуально (с использованием отдельного файла Bootstrap js/dist/*.js), или все сразу, используя bootstrap.js или минифицированный bootstrap.min.js (не включайте оба).

Если Вы используете бандлер (Webpack, Rollup…), Вы можете использовать файлы /js/dist/*.js, готовые для UMD.

Зависимости

Некоторые плагины и компоненты CSS зависят от других плагинов. Если Вы включаете плагины по отдельности, обязательно проверьте наличие этих зависимостей в документации. Также обратите внимание, что все плагины зависят от jQuery (это означает, что jQuery должен быть включен перед файлами плагинов). Обратитесь к нашему package.json, чтобы узнать, какие версии jQuery поддерживаются.

Наши раскрывающиеся списки, всплывающие окна и всплывающие подсказки также зависят от Popper.js.

Атрибуты данных

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

Однако в некоторых ситуациях может потребоваться отключить эту функцию. Чтобы отключить API атрибутов данных, отмените привязку всех событий к документу, имеющему пространство имен с помощью data-api, например:

$(document).off('.data-api')

В качестве альтернативы, чтобы настроить таргетинг на конкретный плагин, просто включите имя плагина в качестве пространства имен вместе с пространством имен data-api следующим образом:

$(document).off('.alert.data-api')

События

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

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

$('#myModal').on('show.bs.modal', function (event) {
  if (!data) {
    return event.preventDefault() // останавливает отображение модального окна
  }
})

Программный API

Мы также считаем, что у Вас должна быть возможность использовать все плагины Bootstrap исключительно через JavaScript API. Все общедоступные API-интерфейсы представляют собой единые, объединяемые в цепочки методы и возвращают коллекцию, на которую были выполнены действия.

$('.btn.danger').button('toggle').addClass('fat')

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

$('#myModal').modal() // инициализирован по умолчанию
$('#myModal').modal({ keyboard: false }) // инициализирован без клавиатуры
$('#myModal').modal('show') // немедленно инициализирует и вызывает show

Каждый плагин также предоставляет свой необработанный конструктор Constructor в свойстве: $.fn.popover.Constructor. Если Вы хотите получить конкретный экземпляр плагина, получите его прямо из элемента: $('[rel="popover"]').data('popover').

Асинхронные функции и переходы

Все программные методы API асинхронны и возвращаются вызывающей стороне после начала перехода, но до его завершения.

Чтобы выполнить действие после завершения перехода, Вы можете прослушать соответствующее событие.

$('#myCollapse').on('shown.bs.collapse', function (event) {
  // Действие, выполняемое после раскрытия сворачиваемой области
})

Кроме того, вызов метода переходного компонента будет проигнорирован.

$('#myCarousel').on('slid.bs.carousel', function (event) {
  $('#myCarousel').carousel('2') // Перейдет к слайду 2, как только переход к слайду 1 завершится
})

$('#myCarousel').carousel('1') // Начнется переход к слайду 1 и вернется к вызывающему
$('#myCarousel').carousel('2') // !! Будет проигнорировано, так как переход к слайду 1 не завершен !!

Настройки по умолчанию

Вы можете изменить настройки плагина по умолчанию, изменив его объект Constructor.Default:

// изменяет значение по умолчанию для опции `keyboard` модального плагина на false
$.fn.modal.Constructor.Default.keyboard = false

Нет конфликта

Иногда необходимо использовать плагины Bootstrap с другими фреймворками пользовательского интерфейса. В этих обстоятельствах иногда могут возникать конфликты пространств имен. Если это произойдет, Вы можете вызвать .noConflict в плагине, значение которого Вы хотите вернуть.

var bootstrapButton = $.fn.button.noConflict() // вернуть $.fn.button к ранее присвоенному значению
$.fn.bootstrapBtn = bootstrapButton // дать $().bootstrapBtn функциональность Bootstrap

Номера версий

Доступ к версии каждого из плагинов Bootstrap jQuery можно получить через свойство VERSION конструктора плагина. Например, для плагина всплывающей подсказки:

$.fn.tooltip.Constructor.VERSION // => "4.6.2"

Никаких специальных резервных вариантов при отключенном JavaScript

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

Util

Все файлы JavaScript в Bootstrap зависят от util.js, и он должен быть включен вместе с другими файлами JavaScript. Если Вы используете скомпилированный (или минифицированный) файл bootstrap.js, нет необходимости включать его - он уже есть.

util.js включает служебные функции и базовый помощник для событий transitionEnd, а также эмулятор перехода CSS. Он используется другими плагинами для проверки поддержки переходов CSS и для обнаружения зависших переходов.

Sanitizer

Всплывающие подсказки и всплывающие окна используют наше встроенное средство очистки для очистки параметров, принимающих HTML.

Значение по умолчанию whiteList следующее:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
  // Глобальные атрибуты разрешены для любого указанного ниже элемента.
  '*': ['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: []
}

Если Вы хотите добавить новые значения в этот белый список whiteList по умолчанию, Вы можете сделать следующее:

var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList

// Разрешить элементы таблицы
myDefaultWhiteList.table = []

// Чтобы разрешить элементы td и атрибуты параметров данных в элементах td
myDefaultWhiteList.td = ['data-option']

// Вы можете отправить собственное регулярное выражение для проверки своих атрибутов.
// Будьте осторожны, чтобы Ваши регулярные выражения были слишком слабыми
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)

Если Вы хотите обойти наше средство очистки, потому что предпочитаете использовать специальную библиотеку, например DOMPurify, Вам следует сделать следующее:

$('#yourTooltip').tooltip({
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})