JavaScript
使用我们可选的 JavaScript 插件让 Bootstrap 栩栩如生。了解每个插件、我们的数据和编程 API 选项等。
单独或编译
插件可以单独包含(使用 Bootstrap 的 individual js/dist/*.js
),或者使用bootstrap.js
或缩小后的所有插件bootstrap.min.js
(不要同时包含两者)。
如果您使用捆绑器(Webpack、Rollup…),您可以使用/js/dist/*.js
已准备好 UMD 的文件。
使用 Bootstrap 作为模块
我们提供了一个构建为ESM
(bootstrap.esm.js
和) 的 Bootstrap 版本,如果您的目标浏览器支持它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>
不兼容的插件
由于浏览器的限制,我们的一些插件,即 Dropdown、Tooltip 和 Popover 插件,不能在<script>
带有类型的标签中使用,module
因为它们依赖于 Popper。有关该问题的更多信息,请参见此处。
依赖项
一些插件和 CSS 组件依赖于其他插件。如果您单独包含插件,请确保在文档中检查这些依赖项。
我们的下拉菜单、弹出框和工具提示也依赖于Popper。
还想使用 jQuery?这是可能的!
Bootstrap 5 被设计为在没有 jQuery 的情况下使用,但仍然可以将我们的组件与 jQuery 一起使用。如果 BootstrapjQuery
在window
对象中检测到,它会将我们所有的组件添加到 jQuery 的插件系统中;这意味着您将能够$('[data-bs-toggle="tooltip"]').tooltip()
启用工具提示。我们的其他组件也是如此。
数据属性
几乎所有的 Bootstrap 插件都可以通过 HTML 单独启用和配置数据属性(我们使用 JavaScript 功能的首选方式)。确保仅在单个元素上使用一组数据属性(例如,您不能从同一个按钮触发工具提示和模式。)
选择器
目前要查询 DOM 元素,我们使用本地方法querySelector
,querySelectorAll
出于性能原因,您必须使用有效的选择器。如果您使用特殊的选择器,例如:collapse:Example
一定要转义它们。
活动
Bootstrap 为大多数插件的独特操作提供自定义事件。通常,这些以不定式和过去分词形式出现 - 其中不定式(例如show
)在事件开始时触发,其过去分词形式(例如shown
)在动作完成时触发。
所有不定式事件都提供preventDefault()
功能。这提供了在动作开始之前停止执行的能力。从事件处理程序返回 false 也会自动调用preventDefault()
.
var myModal = document.getElementById('myModal')
myModal.addEventListener('show.bs.modal', function (event) {
if (!data) {
return event.preventDefault() // stops modal from being shown
}
})
jQuery 事件
jQuery
如果对象中存在jQuerywindow
并且没有data-bs-no-jquery
设置属性,Bootstrap 将检测 jQuery <body>
。如果找到 jQuery,Bootstrap 将通过 jQuery 的事件系统发出事件。所以如果你想监听 Bootstrap 的事件,你必须使用 jQuery 方法 ( .on
, .one
) 而不是addEventListener
.
$('#myTab a').on('shown.bs.tab', function () {
// do something...
})
程序化 API
所有构造函数都接受一个可选的选项对象或什么都不接受(它使用其默认行为启动插件):
var myModalEl = document.getElementById('myModal')
var modal = new bootstrap.Modal(myModalEl) // initialized with defaults
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard
如果你想获得一个特定的插件实例,每个插件都会公开一个getInstance
方法。要直接从元素中检索它,请执行以下操作bootstrap.Popover.getInstance(myPopoverEl)
:
构造函数中的 CSS 选择器
您还可以使用 CSS 选择器作为第一个参数而不是 DOM 元素来初始化插件。目前,该querySelector
方法可以找到插件的元素,因为我们的插件仅支持单个元素。
var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
异步函数和转换
所有编程 API 方法都是异步的,并在转换开始但在结束之前返回给调用者。
为了在转换完成后执行一个动作,您可以监听相应的事件。
var myCollapseEl = document.getElementById('myCollapse')
myCollapseEl.addEventListener('shown.bs.collapse', function (event) {
// Action to execute once the collapsible area is expanded
})
此外,对过渡组件的方法调用将被忽略。
var myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance
myCarouselEl.addEventListener('slid.bs.carousel', function (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 !!
默认设置
您可以通过修改插件的Constructor.Default
对象来更改插件的默认设置:
// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false
没有冲突(仅当您使用 jQuery 时)
有时需要将 Bootstrap 插件与其他 UI 框架一起使用。在这些情况下,有时会发生命名空间冲突。如果发生这种情况,您可以调用.noConflict
您希望恢复其值的插件。
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
版本号
每个 Bootstrap 插件的版本都可以通过VERSION
插件构造函数的属性来访问。例如,对于工具提示插件:
bootstrap.Tooltip.VERSION // => "5.0.2"
禁用 JavaScript 时没有特殊的回退
当 JavaScript 被禁用时,Bootstrap 的插件不会特别优雅地回退。如果您关心这种情况下的用户体验,请使用<noscript>
向您的用户解释情况(以及如何重新启用 JavaScript),和/或添加您自己的自定义后备。
第三方库
Bootstrap 不正式支持第三方 JavaScript 库,如 Prototype 或 jQuery UI。尽管有.noConflict
命名空间的事件,但您可能需要自行修复兼容性问题。
消毒剂
工具提示和弹出框使用我们内置的清理程序来清理接受 HTML 的选项。
默认allowList
值如下:
var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var 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
可以执行以下操作:
var 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
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)
如果您想绕过我们的清理程序,因为您更喜欢使用专用库,例如 DOMPurify,您应该执行以下操作:
var yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
sanitizeFn: function (content) {
return DOMPurify.sanitize(content)
}
})