Skip to main content Skip to docs navigation

JavaScript

使用我们可选的 JavaScript 插件让 Bootstrap 变得栩栩如生。了解每个插件、我们的数据和编程 API 选项等。

目录

单独或编译

¥Individual or compiled

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

¥Plugins can be included individually (using Bootstrap’s individual js/dist/*.js), or all at once using bootstrap.js or the minified bootstrap.min.js (don’t include both).

如果你使用打包器（Webpack、Parcel、Vite…），你可以使用 UMD 就绪的 /js/dist/*.js 文件。

¥If you use a bundler (Webpack, Parcel, Vite…), you can use /js/dist/*.js files which are UMD ready.

与 JavaScript 框架一起使用

¥Usage with JavaScript frameworks

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

¥While the Bootstrap CSS can be used with any framework, the Bootstrap JavaScript is not fully compatible with JavaScript frameworks like React, Vue, and Angular which assume full knowledge of the DOM. Both Bootstrap and the framework may attempt to mutate the same DOM element, resulting in bugs like dropdowns that are stuck in the “open” position.

对于使用此类框架的人来说，更好的选择是使用特定于框架的包而不是 Bootstrap JavaScript。以下是一些最受欢迎的选项：

¥A better alternative for those using this type of frameworks is to use a framework-specific package instead of the Bootstrap JavaScript. Here are some of the most popular options:

Try it yourself! Download the source code and working demo for using Bootstrap with React, Next.js, and React Bootstrap from the twbs/examples repository. You can also open the example in StackBlitz.

使用 Bootstrap 作为模块

¥Using Bootstrap as a module

Try it yourself! Download the source code and working demo for using Bootstrap as an ES module from the twbs/examples repository. You can also open the example in StackBlitz.

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

¥We provide a version of Bootstrap built as ESM (bootstrap.esm.js and bootstrap.esm.min.js) which allows you to use Bootstrap as a module in the browser, if your targeted browsers support it.

<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 中，如下所示：

¥Compared to JS bundlers, using ESM in the browser requires you to use the full path and filename instead of the module name. Read more about JS modules in the browser. That’s why we use 'bootstrap.esm.min.js' instead of 'bootstrap' above. However, this is further complicated by our Popper dependency, which imports Popper into our JavaScript like so:

import * as Popper from "@popperjs/core"

如果你按原样尝试此操作，你将在控制台中看到如下错误：

¥If you try this as-is, you’ll see an error in the console like the following:

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

要解决此问题，你可以使用 importmap 来解析任意模块名称以完成路径。如果你的 目标浏览器 不支持 importmap，你将需要使用 es-module-shims 项目。以下是 Bootstrap 和 Popper 的工作原理：

¥To fix this, you can use an importmap to resolve the arbitrary module names to complete paths. If your targeted browsers do not support importmap, you’ll need to use the es-module-shims project. Here’s how it works for Bootstrap and 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-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" 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>

依赖

¥Dependencies

一些插件和 CSS 组件依赖于其他插件。如果你单独包含插件，请务必在文档中检查这些依赖。

¥Some plugins and CSS components depend on other plugins. If you include plugins individually, make sure to check for these dependencies in the docs.

我们的下拉菜单、弹出窗口和工具提示也依赖于 Popper。

¥Our dropdowns, popovers, and tooltips also depend on Popper.

数据属性

¥Data attributes

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

¥Nearly all Bootstrap plugins can be enabled and configured through HTML alone with data attributes (our preferred way of using JavaScript functionality). Be sure to only use one set of data attributes on a single element (e.g., you cannot trigger a tooltip and modal from the same button.)

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

选择器

¥Selectors

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

¥We use the native querySelector and querySelectorAll methods to query DOM elements for performance reasons, so you must use valid selectors. If you use special selectors like collapse:Example, be sure to escape them.

活动

¥Events

Bootstrap 为大多数插件的独特操作提供自定义事件。一般来说，它们采用不定式和过去分词形式 - 其中不定式（例如 show）在事件开始时触发，其过去分词形式（例如 show）在事件开始时触发。shown) 在完成操作时触发。

¥Bootstrap provides custom events for most plugins’ unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. show) is triggered at the start of an event, and its past participle form (ex. shown) is triggered on the completion of an action.

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

¥All infinitive events provide preventDefault() functionality. This provides the ability to stop the execution of an action before it starts. Returning false from an event handler will also automatically call preventDefault().

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

myModal.addEventListener('show.bs.modal', event => {
  return event.preventDefault() // stops modal from being shown
})

程序化 API

¥Programmatic API

所有构造函数都接受一个可选的选项对象或不接受任何内容（这会以其默认行为启动插件）：

¥All constructors accept an optional options object or nothing (which initiates a plugin with its default behavior):

const myModalEl = document.querySelector('#myModal')
const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

如果你想获取特定的插件实例，每个插件都会公开一个 getInstance 方法。例如，要直接从元素检索实例：

¥If you’d like to get a particular plugin instance, each plugin exposes a getInstance method. For example, to retrieve an instance directly from an element:

bootstrap.Popover.getInstance(myPopoverEl)

如果未通过请求的元素启动实例，则此方法将返回 null。

¥This method will return null if an instance is not initiated over the requested element.

或者，getOrCreateInstance 可用于获取与 DOM 元素关联的实例，或者创建一个新实例以防未初始化。

¥Alternatively, getOrCreateInstance can be used to get the instance associated with a DOM element, or create a new one in case it wasn’t initialized.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

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

¥In case an instance wasn’t initialized, it may accept and use an optional configuration object as second argument.

构造函数中的 CSS 选择器

¥CSS selectors in constructors

除了 getInstance 和 getOrCreateInstance 方法之外，所有插件构造函数都可以接受 DOM 元素或有效的 CSS 选择器 作为第一个参数。插件元素是通过 querySelector 方法找到的，因为我们的插件仅支持单个元素。

¥In addition to the getInstance and getOrCreateInstance methods, all plugin constructors can accept a DOM element or a valid CSS selector as the first argument. Plugin elements are found with the querySelector method since our plugins only support a single element.

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

异步函数和转换

¥Asynchronous functions and transitions

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

¥All programmatic API methods are asynchronous and return to the caller once the transition is started, but before it ends. In order to execute an action once the transition is complete, you can listen to the corresponding event.

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

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Action to execute once the collapsible area is expanded
})

此外，对转换组件的方法调用将被忽略。

¥In addition, a method call on a transitioning component will be ignored.

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

dispose 方法

¥dispose method

虽然在 hide() 之后立即使用 dispose 方法似乎是正确的，但它会导致不正确的结果。这是问题使用的示例：

¥While it may seem correct to use the dispose method immediately after hide(), it will lead to incorrect results. Here’s an example of the problem use:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

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

默认设置

¥Default settings

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

¥You can change the default settings for a plugin by modifying the plugin’s Constructor.Default object:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

方法和属性

¥Methods and properties

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

¥Every Bootstrap plugin exposes the following methods and static properties.

Method Description
dispose Destroys an element’s modal. (Removes stored data on the DOM element)
getInstance Static method which allows you to get the modal instance associated with a DOM element.
getOrCreateInstance Static method which allows you to get the modal instance associated with a DOM element, or create a new one in case it wasn’t initialized.
Static property Description
NAME Returns the plugin name. (Example: bootstrap.Tooltip.NAME)
VERSION The version of each of Bootstrap’s plugins can be accessed via the VERSION property of the plugin’s constructor (Example: bootstrap.Tooltip.VERSION)

Sanitizer

工具提示和弹出框使用我们的内置清理程序来清理接受 HTML 的选项。

¥Tooltips and Popovers use our built-in sanitizer to sanitize options which accept HTML.

默认 allowList 值如下：

¥The default allowList value is the following:

js/src/util/sanitizer.js 
const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i

export const DefaultAllowlist = {
  // 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: [],
  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 添加新值，你可以执行以下操作：

¥If you want to add new values to this default allowList you can do the following:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// To allow table elements
myDefaultAllowList.table = []

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ['data-bs-option']

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

如果你因为更喜欢使用专用库（例如 DOM 纯化）而想绕过我们的消毒程序，则应该执行以下操作：

¥If you want to bypass our sanitizer because you prefer to use a dedicated library, for example DOMPurify, you should do the following:

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

可以选择使用 jQuery

¥Optionally using jQuery

在 Bootstrap 5 中你不需要 jQuery，但仍然可以通过 jQuery 使用我们的组件。如果 Bootstrap 在 window 对象中检测到 jQuery，它会将我们的所有组件添加到 jQuery 的插件系统中。这允许你执行以下操作：

¥You don’t need jQuery in Bootstrap 5, but it’s still possible to use our components with jQuery. If Bootstrap detects jQuery in the window object, it’ll add all of our components in jQuery’s plugin system. This allows you to do the following:

// to enable tooltips with the default configuration
$('[data-bs-toggle="tooltip"]').tooltip()

// to initialize tooltips with given configuration
$('[data-bs-toggle="tooltip"]').tooltip({
  boundary: 'clippingParents',
  customClass: 'myClass'
})

// to trigger the `show` method
$('#myTooltip').tooltip('show')

我们的其他组件也是如此。

¥The same goes for our other components.

没有冲突

¥No conflict

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

¥Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call .noConflict on the plugin you wish to revert the value of.

const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

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

¥Bootstrap does not officially support third-party JavaScript libraries like Prototype or jQuery UI. Despite .noConflict and namespaced events, there may be compatibility problems that you need to fix on your own.

jQuery 事件

¥jQuery events

如果 jQuery 存在于 window 对象中并且 <body> 上没有设置 data-bs-no-jquery 属性，Bootstrap 将检测 jQuery。如果找到 jQuery，Bootstrap 将通过 jQuery 的事件系统触发事件。因此，如果你想监听 Bootstrap 的事件，则必须使用 jQuery 方法（.on、.one）而不是 addEventListener。

¥Bootstrap will detect jQuery if jQuery is present in the window object and there is no data-bs-no-jquery attribute set on <body>. If jQuery is found, Bootstrap will emit events thanks to jQuery’s event system. So if you want to listen to Bootstrap’s events, you’ll have to use the jQuery methods (.on, .one) instead of addEventListener.

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

禁用 JavaScript

¥Disabled JavaScript

当 JavaScript 被禁用时，Bootstrap 的插件没有特殊的后备措施。如果你关心这种情况下的用户体验，请使用 <noscript> 向你的用户解释情况（以及如何重新启用 JavaScript），和/或添加你自己的自定义后备。

¥Bootstrap’s plugins have no special fallback when JavaScript is disabled. If you care about the user experience in this case, use <noscript> to explain the situation (and how to re-enable JavaScript) to your users, and/or add your own custom fallbacks.