JavaScript

Bring Bootstrap to life with our optional JavaScript plugins built on jQuery. Learn about each plugin, our data and programmatic API options, and more.

单个还是整体引用

Bootstrap 插件可以单个引用（使用 Bootstrap 各插件的独立 *.js 文件），或者通过 bootstrap.js 文件或压缩后的 bootstrap.min.js 文件一次性引入（不要两个文件全部引入）。

依赖关系

某些插件和 CSS 组件依赖其他插件。如果你引入的是单个插件，务必在文档中查看其是否有额外依赖。另外还要注意，所有插件都依赖 jQuery （也就是说 jQuery 必须在所有插件 之前 引入）。请参考 package.json 文件以了解哪个版本的 jQuery 是被支持的。

下拉菜单（dropdowns）、提示框（popovers）和工具提示框（tooltips）组件还额外依赖 Popper.js。

data 属性

几乎所有 Bootstrap 插件都可以通过带有 data 属性的 HTML 代码开启并配置 （这中使用 JavaScript 功能的方式是我们推荐的）。注意，在一个元素上只能设置一个 data 属性（例如，你无法在同一个按钮上同时触发工具提示框和模态框）。

然而，在某些情况下可能需要禁用此功能。如需禁止 data 属性 API ，可以通过 data-api 参数在 document 命名空间中解绑所有事件。

$(document).off('.data-api')

另外，如果只是针对某个特定插件，只需在调用时在 data-api 命名空间的前面添加上插件名即可，如下所示：

$(document).off('.alert.data-api')

事件

Bootstrap 为大多数插件唯一的独特行为提供了自定义的事件。一般来说，这些事件都有不定式和过去式两种动词的命名形式 - 不定式形式的动词（例如 show）表示其在事件开始时被触发；而过去式动词（例如 shown ）表示在动作执行完毕之后被触发。

所有以不定式形式的动词命名的事件都提供了 preventDefault() 功能。这就赋予你在动作开始执行前将其停止的能力。在事件处理函数中返回 false 也能够自动调用 preventDefault()。

$('#myModal').on('show.bs.modal', function (e) {
  if (!data) return e.preventDefault() // 停止模态框的展示
})

编程式 API

我们坚信你应当能够通过纯 JavaScript API 的方式调用所有 Bootstrap 插件。所有公开的 API 都是单一、可链式调用的方法，并且全部返回被执行元素的集合。

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

所有方法都可以接受一个可选的对象（object）类型参数，或者某写特定方法也可以接受字符串作为参数，或者没有参数（通过默认参数初始化一个插件）：

$('#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。如果你希望获得某个插件的实例对象，可以直接从 HTML 元素上获取： $('[rel="popover"]').data('popover')。

异步函数和过渡效果

所有编程式 API 方法都是 异步（asynchronous） 的，在过渡效果启动之后、结束之前 将控制权返回给主调函数。

如需在过渡效果完成时执行某个动作，你可以监听相应的事件。

$('#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 对象来改变其默认设置：

$.fn.modal.Constructor.Default.keyboard = false // changes default for the modal plugin's `keyboard` option to 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 属性获取到。例如工具提示框（tooltip）插件：

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

未对禁用 JavaScript 的浏览器提供补救措施

Bootstrap 插件未对禁用 JavaScript 的浏览器提供补救措施。如果你很关心这种情况下的用户体验问题，请添加 <noscript> 标签向你的用户进行解释（并告诉他们如何开启 JavaScript 支持），或者按照你自己的方式提供补救措施。

Util 文件

Bootstrap 的所有 JavaScript 文件都依赖 util.js 文件，并且此文件已经和其他 JavaScript 文件一起打包在一起了。如果你使用的是预编译（或压缩）的 bootstrap.js 文件，无需额外再将其引入了，因为已经都包含了。

util.js 文件包含了工具函数和针对 transitionEnd 事件的辅助代码，另外还包含了一个 CSS 过渡效果模拟器。它被其他插件用来检测 CSS 过渡效果的支持情况并捕获每一个挂起的过渡效果动画。