JavaScript

通过使用可选的基于 jQuery 构建的 JavaScript 插件，让 Bootstrap 变得栩栩如生。在本章中你将了解每个插件以及 Bootstrap 提供的 data 和编程式 API 等更多信息。

单个插件或集成包

每个插件都可以被单独引入（使用对应每个 Bootstrap 插件的 js/dist/*.js 文件），也可以通过 bootstrap.js 或压缩版的 bootstrap.min.js 文件一次性引入所有插件（选一个即可，不要同时使用）。

如果使用打包程序（Webpack、Rollup 等），你可以使用支持 UMD 格式的 /js/dist/*.js 文件。

依赖项

某些插件和 CSS 组件依赖于其它插件。如果你选择单独引入某个插件，请确保在文档中查明其依赖项。另外需要注意的是 所有插件都依赖 jQuery （也就是说，jQuery 必须在其它插件 之前 被引入）。请参考 package.json 文件 以了解所支持的 jQuery 版本。

下拉菜单（dropdown）、弹出框（popover）和工具提示（tooltip）组件依赖 Popper。

插件的 data 属性 API

几乎所有的 Bootstrap 插件都可以通过带有 data 属性的 HTML 元素单独开启和配置（我们推荐 JavaScript API 为首选方式）。请确保 仅在单个 HTML 元素上使用同一个插件的 data 属性 （例如，你不能通过同一按钮触发工具提示和模态框。）

不过，在某些情况下，你可能需要禁用此功能。如需禁用基于 data 属性的 API，请将 document 对象上的以 data-api 为命名空间的所有事件解绑，如下所示：

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

另外，如需禁用某个特定插件，只需将插件名作为命名空间并将 data-api 作为后缀，如下所示：

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

事件

Bootstrap 为大多数插件的独特行为提供了自定义事件。通常，事件的命名以不定式或过去分词形式出现，例如，在事件开始时触发的事件名时不定式形式的（例如 show），在事件完成时触发的事件名是过去分词形式的（例如 shown）。

所有不定式形式命名的事件都提供 preventDefault() 功能。这就赋予了你在动作开始之前将其停止的能力。如果事件处理函数的返回值是 false，将自动调用 preventDefault()。

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

编程式 API

我们觉得你应该会需要完全通过 JavaScript API 的方式来使用所有的 Bootstrap 插件。所有开放的 API 都是独立、可链式调用的方法，并且返回被操作的元素集合。

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

所有方法都可以接受三种参数形式：对象类型的参数、字符串类型的参数（将被当作是某个方法的名称）或没有参数（将以默认行为启动插件）：

$('#myModal').modal() // 以默认值启动插件
$('#myModal').modal({ keyboard: false }) // 启动插件时将 keyboard 设置为 false
$('#myModal').modal('show') // 启动插件并立即调用 show 方法

每个插件都通过 Constructor 属性对外开放其原始的构造函数： $.fn.popover.Constructor。如果你想获取某个插件的特定实例，请直接从其对应的元素中获取它： $('[rel="popover"]').data('popover')。

异步编程和 transitions

所有编程形式的 API 方法都是 异步的，并在 transition 开始之后、结束之前返回到调用者。

为了在 transition 完成后执行某个动作，你可以监听相应的事件。

$('#myCollapse').on('shown.bs.collapse', function (event) {
  // 可折叠区域被展开时，此处的动作将被执行一次
})

另外，对 正在 transitioning 状态的组件调用的任何方法都将被忽略。

$('#myCarousel').on('slid.bs.carousel', function (event) {
  $('#myCarousel').carousel('2') // 当滑动到幻灯片 1 之后，将立即滑动到幻灯片 2
})

$('#myCarousel').carousel('1') // 开始滑动到幻灯片 1 并返回到回调者
$('#myCarousel').carousel('2') // !! 将会被忽略，因为滑动到幻灯片 1 的转换动作还未完成 !!

默认设置

你可以通过修改插件的 Constructor.Default 对象来更改插件的默认设置：

// 将模态框（modal）插件的 `keyboard` 的默认值修改为 false
$.fn.modal.Constructor.Default.keyboard = false

避免冲突

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

var bootstrapButton = $.fn.button.noConflict() // 重置 $.fn.button 为先前的值
$.fn.bootstrapBtn = bootstrapButton // 为 $().bootstrapBtn 赋予 Bootstrap 的功能

版本号

每个 Bootstrap 的 jQuery 插件都可以通过其构造函数上的 VERSION 属性进行访问。例如，以工具提示（tooltip）插件为例：

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

JavaScript 被禁用的话没有降级方案

一旦 JavaScript 被禁用，Bootstrap 的插件没有优雅降级的方案。如果你很关心在这种情况下的用户体验，请使用 <noscript> 标签并向你的用户解释情况（以及重新启用 JavaScript 的方法），和/或添加你自己的降级方案。

util.js 文件

Bootstrap 的所有 JavaScript 文件都依赖 util.js 文件，并且此文件必须与其它 JavaScript 文件放在一起使用。如果你使用的是经过编译（或压缩）的 bootstrap.js 文件，则已经包含了此文件了。

util.js 包含了一些工具函数，和 transitionEnd 事件的一个基本的辅助函数，以及一个 CSS transition 的模拟器。其它插件使用此文件来检查是否支持 CSS transition 情况并捕获挂起的（hanging） transitions。

清理程序

工具提示（tooltip）和弹出框（popover）可以接受 HTML 代码作为参数，但会使用 Bootstrap 内置的清理程序对 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

// 添加 table 元素
myDefaultWhiteList.table = []

// 添加 td 元素以及 td 元素的 data-option 属性
myDefaultWhiteList.td = ['data-option']

// 你可以添加自定义的正则表达式来对属性进行校验。
// 请提防过于宽松的正则表达式
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)

如果你因为喜欢使用专用的工具库（例如 DOMPurify）并想绕过 Bootstrap 的清理程序，则可以这样操作：

$('#yourTooltip').tooltip({
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})