JavaScript 脚本

Bootstrap 包括一些 JavaScript 帮助用户做出更加充满生机、活动的项目。欢迎学习更多关于如何去调用动态事件、灵活展示的数据和编程性的API选项等。

本页导航↓

单个引用或者编译

插件可以单独包含(使用Bootstrap的独立 js/dist/*.js)，也可以同时使用 bootstrap.js 或压缩的 bootstrap.min.js (不要同时包含两个)。

如果使用bundler（Webpack，Rollup ...），则可以使用UMD就绪的/js/dist/*.js文件。

使用Bootstrap模块

Bootstrap提供了一个以 ESM 构建的Bootstrap版本(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>

不兼容的插件

由于浏览器的限制，某些插件，例如Dropdown，Tooltip和Popover插件，不能在 <script> 中使用带有 <module> 类型的标签，因为它们取决于Popper。关于这个问题的更多信息

依赖关系

一些插件和CSS组件依赖于其他插件。如果你单独调用某个插件，请先在文档中检查它们的依赖关系。

比如下拉菜单dropdowns、提示组件popovers、冒泡组件等都提依赖于Popper。

还想使用jQuery吗?这是可能的!

Bootstrap 5是为不使用jQuery而设计的，如果你想，依旧可以使用jQuery的组件。Bootstrap在窗口对象中检测到jQuery，它会在jQuery的插件系统中添加我们所有的组件。这说明你可以可以通过$('[data-bs-toggle="tooltip"]').tooltip() 启用工具提示。其他组件也是如此。

数据属性

几乎所有的引导插件都可以通过带有数据属性的HTML(我们使用JavaScript功能的首选方式)来启用和配置。确保在单个元素上只使用一组数据属性(例如，不能从同一个按钮触发工具提示和模态)。

选择器

目前，为了查询DOM元素，我们使用原生方法 querySelector 和 querySelectorAll ，因为性能原因，所以必须使用有效的选择器。如果您使用特殊的选择器，例如: collapse:Example ，请确保对它们进行转义。

JS事件(Event)

Bootstrap为大多数插件的独特动作提供自定义事件。一般来说，这些动词都有不定式和过去分词形式，其中不定式(如 shown)是在事件开始时触发的,它的过去分词形式(如 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 出现在 window 对象中，并且没有设置 data-bs-no-jquery 属性，那么Bootstrap将检测jQuery。如果发现了jQuery, Bootstrap将通过jQuery的事件系统发出事件。因此，如果您想监听Bootstrap的事件，就必须使用jQuery方法(.on，.one)而不是 addEventListener。

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

编程化的 API

所有的构造函数都接受一个可选的option对象，或者什么都不接受(这将启动一个默认行为的插件):

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)。

异步函数和转换

所有编程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的情况下)

有时，在其他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.1"

当JavaScript被禁用时，没有特殊的回调机制

Bootstrap插件在JavaScript被禁用时没有特殊的回调方式。如果你比较关心用户体验的话，可用 <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)
}
})