JavaScript
Запустите Bootstrap с нашими дополнительными плагинами JavaScript построенными на jQuery. Узнайте о каждом плагине, наших данных и программных API-интерфейсах и т.п.
Индивидуальные или компилированные
Плагины можно подключать по одному (файлами js/dist/*.js
) или все сразу – с помощью bootstrap.js
или «облегченного» bootstrap.min.js
(не подключайте оба сразу).
Если вы используете например, Webpack, Rollup..., то вы можете использовать файлы /js/dist/*.js
готовые к UMD.
Зависимости
Некоторые плагины и компоненты CSS зависят от других плагинов. Если вы подключаете плагины по одному, проверьте существование зависимостей в документации. Также заметим, что все плагины зависят от jQuery (т.е. в файле HTML jQuery надо подключать перед плагинами). Загляните сюда bower.json
для получения информации по поддерживаемым версиям jQuery.
Всплывающие подсказки (по наведению) и «всплывающие окна» (по клику мыши) зависят от библиотеки Popper.js.
Дата-атрибуты
все плагины Bootstrap можно подключить и настроить в HTML через дата-атрибуты Bootstrap «предпочитает» этот метод использования функционала JS. Удостоверьтесь, что в одном элементе используется лишь один набор атрибутов (т.е., не получится запустить всплывающие подсказки и «всплывающие окна» из одной кнопки).
Однако иногда может понадобиться выключить эту способность. Для выключения API атрибута, «открепите» все обработчики событий документа, лежащие в пространстве имен data-api
:
$(document).off('.data-api')
В качестве альтернативы, чтобы настроить таргетинг на конкретный плагин, просто включите имя плагина в качестве пространства имен вместе с пространством имен data-api следующим образом:
$(document).off('.alert.data-api')
Селекторы
В настоящее время для запроса элементов DOM мы используем собственные методы querySelector
и querySelectorAll
по соображениям производительности, поэтому вы должны использовать допустимые селекторы.
Если вы используете специальные селекторы, например: collapse:Example
, обязательно избегайте их.
События
Bootstrap предлагает ряд собственных событий для уникальных действий большинства плагинов. В целом, эти события обозначаются инфинитивом и прошедшей формой причастия – где инфинитив (например, show
) запускается в начале события, а его причастие (например, shown
) – по окончанию события.
Все инфинитивные события предоставляют функциональные возможности preventDefault()
. Это дает возможность остановить выполнение действия до его начала. Возвращение false из обработчика событий также автоматически вызовет preventDefault()
.
$('#myModal').on('show.bs.modal', function (event) {
if (!data) {
return event.preventDefault() // stops modal from being shown
}
})
Алгоритмическое API
Мы решили дать вам возможность использовать все плагины Bootstrap прямиком через JS API. Все свободно распространяемые API – это отдельные методы «цепочки вызовов», возвращающие набор параметров, над которыми производилось действие.
$('.btn.danger').button('toggle').addClass('fat')
Всем методам следует передавать или аргументы, т.е. строку, которая вызывает какой-либо метод, или ничего не передавать (что вызовет действие плагина, заложенное по умолчанию).
$('#myModal').modal() // initialized with defaults
$('#myModal').modal({ keyboard: false }) // initialized with no keyboard
$('#myModal').modal('show') // initializes and invokes show immediately
Также, у каждого плагина может быть вызван конструктор через свойство Constructor
: $.fn.popover.Constructor
. Если вам нужен экземпляр определенного плагина, извлеките его непосредственно из элемента: $('[rel="popover"]').data('popover')
.
Асинхронные функции и библиотека «переходов»
Все методы алгоритмических API асинхронны и возвращают пользователю значение после того, как «переход» начат и до того, как «переход» закончен.
Чтобы выполнить действие по завершению «перехода», вы можете отследить соответствующее событие.
$('#myCollapse').on('shown.bs.collapse', function (e) {
// Action to execute once the collapsible area is expanded
})
Вызов метода на динамическом, изменяющемся компоненте будет проигнорирован.
$('#myCarousel').on('slid.bs.carousel', function (e) {
$('#myCarousel').carousel('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})
$('#myCarousel').carousel('1') // Will start sliding to the slide 1 and returns to the caller
$('#myCarousel').carousel('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!
Установки по умолчанию
Вы можете изменить их для плагина, изменяя объект плагина Constructor.Default
:
// changes default for the modal plugin's `keyboard` option to false
$.fn.modal.Constructor.Default.keyboard = false
Конфликты
Иногда необходимо использовать плагины BS с другими UI – фреймворками. Тогда могут возникнуть проблемы в пространствах имен. В этом случае вы можете вызвать метод .noConflict
на плагине, значение которого вы хотите переназначить.
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
Версии
Версия каждого плагина jQuery может быть узнана через свойство конструктора плагина VERSION
. Например, для плагина всплывающих подсказок:
$.fn.tooltip.Constructor.VERSION // => "4.6.0"
В BS4 нет т.н. fallback’a (т.е. «резервных» стилей для случая «глобальной поломки» верстки на старых браузерах), когда отключен JS
Плагины Bootstrap частично не смогут «подстроить» функциональность вашего сайта в соответствии с параметрами отображения старого браузера, если юзер зайдет на него с такового, или в случае «уничтожения» или «зависания» части кода т.е. на старых браузерах BS4 может не сработать, если там отключен JS. Если вы хотите подсказать юзеру, что делать в таком случае, используйте тэг <noscript>
для пояснений о пере-включении JS.
Сторонние библиотеки
Официально Bootstrap не поддерживает сторонние JavaScript библиотеки, такие как Prototype или UI-jQuery. Несмотря на использование .noConflict
и группированных по функциональности обработчиков событий, при подключении сторонних библиотек могут возникнуть проблемы при компиляции.
Util
Весь JS в Bootstrap зависит от util.js
, который должен подключаться среди прочих JS-файлов, кроме случаев, когда вы пользуетесь компилированным или «облегченным» bootstrap.js
– потому что в этом случае он уже подключен.
util.js
содержит полезные функции и базовый справочник для событий transitionEnd
и эмулятор «переходов» CSS. Этот файл используется другими плагинами для проверки существования поддержки.
Антисептик
Всплывающие подсказки и всплывающие подсказки используют наше встроенное дезинфицирующее средство для очистки параметров, принимающих HTML.
По умолчанию значение белого списка whiteList
следующее:
var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
// 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: []
}
Если вы хотите добавить новые значения в этот whiteList
(белый список) по умолчанию, вы можете сделать следующее:
var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList
// To allow table elements
myDefaultWhiteList.table = []
// To allow td elements and data-option attributes on td elements
myDefaultWhiteList.td = ['data-option']
// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)
Если вы хотите обойти наш антисептик, потому что вы предпочитаете использовать выделенную библиотеку, например, DOMPurify, вы должны сделать следующее:
$('#yourTooltip').tooltip({
sanitizeFn: function (content) {
return DOMPurify.sanitize(content)
}
})