Bootstrap JavaScript插件

Bootstrap 使用基于jQuery构建的JavaScript插件可以变得更加生动活泼。JavaScript 插件插件可以轻松地添加各种交互功能和动态效果，从而增强用户体验，无论是通过简单地在HTML标记中添加data属性，还是通过JavaScript代码来调用API。本篇教程将为大家详细介绍。

一、单个插件/集成包

每个插件都可以被单独引入（使用对应每个 Bootstrap 插件的 js/dist/*.js 文件），也可以通过 bootstrap.js 或压缩版的 bootstrap.min.js 文件一次性引入所有插件（选一个即可，不要同时使用）。如果使用打包程序（Webpack、Rollup 等），可以使用支持 UMD 格式的 /js/dist/*.js 文件。

二、依赖项

如果选择单独引入某个插件，请确保在文档中了解其依赖关系。一些插件和CSS组件可能依赖于其他插件，因此在使用时需要注意。所有插件都依赖于jQuery，这意味着jQuery必须在其他插件之前被引入。另外，下拉菜单（dropdown）、弹出框（popover）和工具提示（tooltip）组件依赖于Popper，因此在使用这些组件时需要先引入Popper。

三、data属性

几乎所有的Bootstrap插件都可以通过带有data属性的HTML元素单独开启和配置（尽管我们推荐JavaScript API为首选方式）。然而，请确保仅在单个HTML元素上使用同一个插件的data属性，比如说，不能通过同一按钮触发工具提示和模态框。不过，在某些情况下，可能需要禁用此功能。如果需要禁用基于data属性的API，请将document对象上以data-api为命名空间的所有事件解绑。如下所示：

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

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

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

选择器：

由于性能的原因，我们使用原生方法querySelector和querySelectorAll来查询DOM元素，大家在操作时必须使用合法的选择器。如果使用特殊的选择器，例如collapse:Example，请确保对其进行转义。

四、事件

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

1、异步编程和 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 的转换动作还未完成 !!

2、默认设置

可以通过修改插件的 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 的方法），和/或添加自己的降级方案。

第三方工具库：Bootstrap 不对第三方工具库提供支持，例如 Prototype 或 jQuery UI。尽管存在 .noConflict 和基于命名空间的事件，但仍可能需要您自行解决兼容性问题。

九、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)
}
})