JavaScript

利用我们基于 jQuery 构建的可选 JavaScript 插件，让 Bootstrap 焕发活力。了解每个插件、我们的数据和编程 API 选项，以及更多内容。

单独或编译

插件可以单独包含（使用 Bootstrap 的单独 js/dist/*.js），或使用 bootstrap.js 或经过压缩的 bootstrap.min.js 一次性包含所有插件（不要同时包含两者）。

如果您使用捆绑器（Webpack、Rollup…），可以使用已准备就绪的 UMD /js/dist/*.js 文件。

依赖项

某些插件和 CSS 组件依赖于其他插件。如果您单独包含插件，请务必在文档中检查这些依赖项。另请注意，所有插件都依赖于 jQuery（这意味着必须在插件文件之前包含 jQuery）。查阅我们的 package.json，以了解支持的 jQuery 版本。

我们的下拉菜单、弹出框和工具提示还依赖于 Popper.js。

数据属性

几乎所有 Bootstrap 插件都可以通过仅使用数据属性（我们首选的 JavaScript 功能使用方式）通过 HTML 来启用和配置。请务必仅对单个元素使用一组数据属性（例如，您无法从同一个按钮触发工具提示和模态框。）

但是，在某些情况下，可能需要禁用此功能。要禁用数据属性 API，请取消绑定所有使用 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() // stops modal from being shown
  }
})

编程 API

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

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

所有方法都应接受一个可选选项对象、一个针对特定方法的字符串，或不接受任何内容（这会使用默认行为启动插件）

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

版本号

可以通过插件构造函数的 VERSION 属性访问每个 Bootstrap jQuery 插件的版本。例如，对于 tooltip 插件

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

在禁用 JavaScript 时无特殊回退

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

第三方库

Bootstrap 不正式支持第三方 JavaScript 库，如 Prototype 或 jQuery UI。尽管有 .noConflict 和命名空间事件，但您可能需要自行修复兼容性问题。

Util

所有 Bootstrap JavaScript 文件都依赖于 util.js，它必须与其他 JavaScript 文件一起包含。如果你正在使用已编译（或已缩小的）bootstrap.js，则无需包含此文件，因为它已经存在。

util.js 包含实用函数和 transitionEnd 事件的基本帮助程序以及 CSS 过渡模拟器。其他插件使用它来检查 CSS 过渡支持并捕获挂起的过渡。

Sanitizer

工具提示和弹出框使用我们的内置消毒器来消毒接受 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)
  }
})