View on GitHub

JavaScript

借助我们基于jQuery构建的可选JavaScript插件，使Bootstrap栩栩如生。了解每个插件，我们的数据和程序化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-apiI同名的文档上的所有事件的绑定，如下所示：

$(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

我们还相信您应该能够通过JavaScript API使用所有 Bootstrap插件。所有公共API都是单一的、可链接的方法，并返回对其执行操作的集合。

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

所有方法都应该接受一个可选的options对象、一个以特定方法为目标的字符串，或者什么都不接受（它以默认行为启动插件）：

$('#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 (event) {
  // Action to execute once the collapsible area is expanded
})

此外， 对转换组件的方法调用将被忽略。

$('#myCarousel').on('slid.bs.carousel', function (event) {
  $('#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

避免冲突

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

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

版本号

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

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

禁用JavaScript时没有特殊的后备方案

当JavaScript被禁用时，Bootstrap的插件不会特别优雅地后退。如果您关心本例中的用户体验，请使用 <noscript> 向用户解释情况（以及如何重新启用JavaScript），和/或添加您自己的自定义回退。

第三方库

Bootstrap并不正式支持Prototype或jQuery UI等第三方JavaScript库。尽管存在 .noConflict和命名空间事件，但可能存在需要您自己解决的兼容性问题。

实用程序

所有 Bootstrap的JavaScript文件都依赖于util.js，它必须与其他JavaScript文件一起包含。如果您使用的是编译的（或压缩的） bootstrap.js，没有必要包括这个，它已经存在了。

util.js 包括实用程序函数、 transitionEnd 事件的基本帮助程序以及CSS转换仿真器。其他插件使用它来检查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)
  }
})