JavaScript

使用我们的可选 JavaScript 插件让 Bootstrap 充满活力。了解每个插件、我们的数据和编程 API 选项等。

On this page

单个插件或集成包

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

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

与 JavaScript 框架配合使用

虽然 Bootstrap CSS 可以与任何框架一起使用，但 Bootstrap JavaScript 与 React、Vue 和 Angular 等 JavaScript 框架并不完全兼容，因为这些框架需要完全了解 DOM。Bootstrap 和框架都可能试图改变相同的 DOM 元素，从而导致下拉菜单卡在 “打开 ”位置等错误。

对于使用这类框架的人来说，更好的选择是使用特定框架的软件包，而不是 Bootstrap JavaScript。以下是一些最流行的选择：

React: React Bootstrap
自己试试看 从 twbs/examples repository下载源代码和使用 Bootstrap 与 React、Next.js 和 React Bootstrap 的演示。您也可以在 StackBlitz 中打开示例。
Vue: BootstrapVue (Bootstrap 4)
Vue 3: BootstrapVueNext (Bootstrap 5, currently in alpha)
Angular: ng-bootstrap

将 Bootstrap 作为模块使用

自己试试看 从 twbs/examples 资源库下载源代码和将 Bootstrap 用作 ES 模块的工作演示。您也可以在 StackBlitz 中打开示例。

我们为 Bootstrap 提供了一个 ESM 模块（bootstrap.esm.js 和 bootstrap.esm.min.js）的版本，如果你的目标浏览器支持的话，你可以在浏览器中将 Bootstrap 作为模块使用。

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

与 JS 捆绑程序相比，在浏览器中使用 ESM 需要使用完整路径和文件名，而不是模块名称。了解更多浏览器中的 JS 模块。这就是我们使用 “bootstrap.esm.min.js ”而不是 “bootstrap ”的原因。然而，我们的 Popper 依赖关系又使问题变得更加复杂，因为我们需要将 Popper 导入 JavaScript 中：

import * as Popper from "@popperjs/core"

如果按 as-is 尝试，控制台中会出现类似下面的错误：

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

要解决这个问题，可以使用 importmap 将任意模块名称解析为完整路径。如果目标浏览器不支持 importmap，则需要使用 es-module-shims 项目。下面是 Bootstrap 和 Popper 的使用方法：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-Y3IQOsa3niuvpqakr8NIT3EETRv0G6tFumi3detLTSYuXBc6XxbPEt9sOg6OcLgO" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.8/dist/esm/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

依赖项

某些插件和 CSS 组件依赖于其它插件。如果你选择单独引入某个插件，请确保在文档中检查其是否存在依赖其它插件的情况。

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

data 属性

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

由于可以通过 data 属性或 JavaScript 传递选项，因此可以在 data-bs- 中附加选项名称，如 data-bs-animation=“{value}”。通过data 属性传递选项时，请确保将选项名称的大小写类型从“camelCase”改为“kebab-case”。例如，使用 data-bs-custom-class=“beautifier” 而不是 data-bs-customClass=“beautifier”。

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

选择器

出于性能考虑，我们使用原生的 querySelector 和 querySelectorAll 方法来查询 DOM 元素，因此您必须使用有效选择器。如果使用特殊的选择器，如 collapse:Example，请务必转义。

事件

Bootstrap 为大多数插件的独特操作提供了自定义事件。一般来说，这些事件有不定式和过去分词两种形式，其中不定式（例如 show）在事件开始时触发，而过去分词形式（例如 shown）则在操作完成时触发。

所有不定式事件都提供 preventDefault()功能。这提供了在动作开始前停止其执行的能力。从事件处理程序返回 false 也会自动调用 preventDefault()。

const myModal = document.querySelector('#myModal')

myModal.addEventListener('show.bs.modal', event => {
  return event.preventDefault() // 阻止模态显示
})

编程式 API

所有构造函数都可以接受对象类型的参数或没有参数（将以默认行为初始化插件）:

const myModalEl = document.querySelector('#myModal')
const modal = new bootstrap.Modal(myModalEl) // 以默认值初始化

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // 以对象参数初始化

如果您想获取某个插件的实例，每个插件都会提供一个 getInstance 方法。例如，直接从元素中获取实例：

bootstrap.Popover.getInstance(myPopoverEl)

如果请求的元素上没有启动实例，该方法将返回 null。

或者，也可以使用 getOrCreateInstance 获取与 DOM 元素相关的实例，或者在未初始化的情况下创建一个新实例。

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

如果实例没有初始化，它可以接受并使用一个可选的配置对象作为第二个参数。

构造函数中的CSS选择器

除了 getInstance 和 getOrCreateInstance 方法外，所有插件构造函数都可以接受 DOM 元素或有效的 CSS 选择器作为第一个参数。由于我们的插件只支持单个元素，因此可使用 querySelector 方法查找插件元素。

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

异步编程和转换

所有编程 API 方法都是异步的，并在transition 开始后、结束前返回给调用者。为了在转换完成后执行操作，您可以监听相应的事件。

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // 展开可折叠区域后要执行的操作
})

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

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // 获取轮播（Carousel）组件的实例

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // 当滑动到幻灯片 1 之后，将立即滑动到幻灯片 2
})

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

`dispose` 方法

在 hide() 之后立即使用 dispose 方法看似正确，但会导致不正确的结果。下面是一个使用问题的示例：

const myModal = document.querySelector('#myModal')
myModal.hide() // 异步

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

默认设置

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

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

方法和属性

每个 Bootstrap 插件都公开以下方法和静态属性。

方法	描述
`dispose`	销毁元素的模态。(删除 DOM 元素上存储的数据
`getInstance`	静态方法，用于获取与 DOM 元素相关联的模态实例。
`getOrCreateInstance`	静态方法，用于获取与 DOM 元素相关联的模态实例，或在未初始化的情况下创建一个新的模态实例。

静态属性	描述
`NAME`	返回插件名称。(例如：`bootstrap.Tooltip.NAME`)
`VERSION`	可以通过插件构造函数的 `VERSION` 属性访问 Bootstrap 各个插件的版本（例如：`bootstrap.Tooltip.VERSION`）。

清理工具

工具提示和弹出窗口使用我们的内置清理工具对接受 HTML 的选项进行清理。

allowList 的默认值如下所示：

js/src/util/sanitizer-zh.js

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i

export const DefaultAllowlist = {
  // 允许在下面提供的任何元素上使用全局属性。
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  dd: [],
  div: [],
  dl: [],
  dt: [],
  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: []
}

如果要向 allowList 添加新值，则可以执行如下操作：

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

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

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

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

如果您想绕过我们的清理程序，因为您更喜欢使用一个专用库，例如 DOMMPurify，您应该执行以下操作：

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

可选用 jQuery

在Bootstrap 5中不需要jQuery，但仍然可以将我们的组件与jQuery结合使用。如果Bootstrap在 “window ”对象中检测到 “jQuery”，它就会在jQuery的插件系统中添加我们的所有组件。这样您就可以进行以下操作：

// 使用默认配置启用工具提示
$('[data-bs-toggle="tooltip"]').tooltip()

// 用给定配置初始化工具提示
$('[data-bs-toggle="tooltip"]').tooltip({
  boundary: 'clippingParents',
  customClass: 'myClass'
})

// 触发 `show` 方法
$('#myTooltip').tooltip('show')

其他组件也是如此。

避免冲突

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

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

Bootstrap 官方不支持 Prototype 或 jQuery UI 等第三方 JavaScript 库。尽管有“.noConflict ”和命名事件，仍可能存在兼容性问题，您需要自行解决。

jQuery 事件

如果 “window ”对象中存在 “jQuery”，且“”上未设置 “data-bs-no-jquery ”属性，Bootstrap 就会检测到 jQuery。如果找到了 jQuery，Bootstrap 就会利用 jQuery 的事件系统发出事件。因此，如果要监听 Bootstrap 的事件，就必须使用 jQuery 方法（.on, .one）而不是 addEventListener。

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})

禁用 JavaScript

当 JavaScript 被禁用时，Bootstrap 的插件没有特殊的回退功能。如果您关心这种情况下的用户体验，请使用 <noscript>向用户说明情况（以及如何重新启用 JavaScript），和/或添加您自己的自定义回退。