JavaScript

使用我们可选的JavaScript插件让Bootstrap活力四射。了解每个插件、我们的数据属性和编程API选项等。

On this page

引入单个插件或整个引入编译好的文件

插件可以单独引入(使用Bootstrap的单独的js/dist/*.js)文件, 或者一次性引入整个bootstrap.js或压缩后的bootstrap.min.js (不要两个都引入)。

如果您使用打包器(如Webpack, Rollup…), 您可以使用/js/dist/*.js文件，他们都支持UMD

将Bootstrap当作一个模块使用

我们提供了一个版本的Bootstrap，它以ESM形式(bootstrap.esm.js和bootstrap.esm.min.js)构建，它允许您将Bootstrap作为一个模块在您的浏览器中使用, 前提是您的浏览器支持ESM。

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'
  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

不兼容的插件

由于浏览器的限制，我们的一些插件，即Dropdown、Tooltip和Popover插件，不能在module类型的<script>标签中使用，因为它们依赖于Popper。有关该问题的更多信息，请参阅模块说明符。

依赖项

一些插件和CSS组件依赖于其他插件。如果您单独包含插件，请确保在文档中检查这些依赖项。

Dropdown、Tooltip和Popover插件依赖于Popper.

还想使用jQuery？这是可以做到的！

Bootstrap 5被设计为在不需要jQuery的情况下使用，但仍然可以将我们的组件与jQuery一起使用。如果Bootstrap检测到jQuery在window对象上，它将添加所有组件到jQuery的插件系统上；这意味着可以直接使用$('[data-bs-toggle="tooltip"]').tooltip()来启用tooltips，其它组件也类似。

数据属性

几乎所有的Bootstrap插件都可以单独通过HTML启用和数据属性配置（这是我们使用Bootstrap JavaScript功能的首选方式）。但应确保仅在单个元素上使用一组数据属性（例如，您不能从同一个按钮触发tooltip和modal。）

Selectors

出于性能原因，目前我们查询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事件

如果window对象中存在jQuery并且<body>上没有设置data-bs-no-jquery属性，Bootstrap将检测 jQuery。如果找到jQuery，Bootstrap将通过jQuery的事件系统发出事件。所以如果你想监听Bootstrap的事件，你必须使用jQuery方法（.on, .one）而不是addEventListener。

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

编程API

所有构造函数都接受一个可选的options对象或什么都不接受（它将使用其默认行为启动插件）：

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

No conflict(仅当使用jQuery时)

有时需要将Bootstrap插件与其他UI框架一起使用。在这些情况下，有时会发生命名空间冲突。如果发生这种情况，您可以在要恢复其值的插件上调用.noConflict。

var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

版本号

可以通过插件构造函数的VERSION属性访问每个Bootstrap插件的版本。例如，对于工具提示(tooltip)插件：

bootstrap.Tooltip.VERSION // => "5.1.3"

禁用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)
  }
})