JavaScript

使用我們可選的 JavaScript 插件讓 Bootstrap 栩栩如生。了解每個插件、我們的數據和編程 API 選項等。

在本頁面

單獨或編譯

插件可以單獨包含（使用 Bootstrap 的 individual js/dist/*.js），或者使用bootstrap.js或縮小後的所有插件bootstrap.min.js（不要同時包含兩者）。

如果您使用捆綁器（Webpack、Parcel、Vite……），您可以使用/js/dist/*.js已準備好 UMD 的文件。

與 JavaScript 框架一起使用

雖然 Bootstrap CSS 可以與任何框架一起使用，但 Bootstrap JavaScript 並不完全兼容 JavaScript 框架，如 React、Vue 和 Angular，它們假定對 DOM 有充分的了解。Bootstrap 和框架都可能試圖改變同一個 DOM 元素，從而導致諸如下拉菜單之類的錯誤，這些錯誤會卡在“打開”位置。

對於使用此類框架的人來說，更好的選擇是使用特定於框架的包而不是Bootstrap JavaScript。以下是一些最受歡迎的選項：

反應：反應引導
Vue：BootstrapVue（目前只支持Vue 2和Bootstrap 4）
角度：ng-bootstrap

使用 Bootstrap 作為模塊

自己試試吧！從twbs/examples 存儲庫下載源代碼和工作演示，以將 Bootstrap 用作 ES 模塊。您也可以在 StackBlitz 中打開示例。

我們提供了一個構建為ESM(bootstrap.esm.js和) 的 Bootstrap 版本，如果您的目標瀏覽器支持它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"

如果您按原樣嘗試此操作，您將在控制台中看到如下錯誤：

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

要解決此問題，您可以使用 animportmap來解析任意模塊名稱以完成路徑。如果您的目標瀏覽器不支持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/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" 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/[email protected]/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/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 組件依賴於其他插件。如果您單獨包含插件，請確保在文檔中檢查這些依賴項。

我們的下拉菜單、彈出框和工具提示也依賴於Popper。

數據屬性

幾乎所有的 Bootstrap 插件都可以通過 HTML 單獨啟用和配置數據屬性（我們使用 JavaScript 功能的首選方式）。確保僅在單個元素上使用一組數據屬性（例如，您不能從同一個按鈕觸發工具提示和模式。）

由於選項可以通過數據屬性或 JavaScript 傳遞，因此您可以將選項名稱附加到data-bs-，如data-bs-animation="{value}". 通過數據屬性傳遞選項時，請確保將選項名稱的大小寫類型從“ camelCase ”更改為“ kebab-case ”。例如，使用data-bs-custom-class="beautifier"代替data-bs-customClass="beautifier".

從 Bootstrap 5.2.0 開始，所有組件都支持一個實驗性的保留數據屬性data-bs-config，該屬性可以將簡單的組件配置作為 JSON 字符串容納。當一個元素具有data-bs-config='{"delay":0, "title":123}'和data-bs-title="456"屬性時，最終title值將是456並且單獨的數據屬性將覆蓋給定的值 on data-bs-config。此外，現有數據屬性能夠容納 JSON 值，例如data-bs-delay='{"show":0,"hide":150}'.

選擇器

出於性能原因，我們使用本機querySelector和方法來查詢 DOM 元素，因此您必須使用有效的選擇器。如果您使用特殊的選擇器，例如，請務必轉義它們。querySelectorAllcollapse:Example

活動

Bootstrap 為大多數插件的獨特操作提供自定義事件。通常，這些以不定式和過去分詞形式出現 - 其中不定式（例如show）在事件開始時觸發，其過去分詞形式（例如shown）在動作完成時觸發。

所有不定式事件都提供preventDefault()功能。這提供了在動作開始之前停止執行的能力。從事件處理程序返回 false 也會自動調用preventDefault().

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

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

程序化 API

所有構造函數都接受一個可選的選項對像或什麼都不接受（它使用其默認行為啟動插件）：

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方法。例如，要直接從元素中檢索實例：

bootstrap.Popover.getInstance(myPopoverEl)

null如果沒有在請求的元素上啟動實例，則此方法將返回。

或者，getOrCreateInstance可用於獲取與 DOM 元素關聯的實例，或創建一個新實例以防它未初始化。

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

如果一個實例沒有被初始化，它可以接受並使用一個可選的配置對像作為第二個參數。

構造函數中的 CSS 選擇器

除了getInstanceandgetOrCreateInstance方法，所有插件構造函數都可以接受一個 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 方法都是異步的，並在轉換開始但在結束之前返回給調用者。為了在轉換完成後執行一個動作，您可以監聽相應的事件。

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

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

此外，過渡組件上的方法調用將被忽略。

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雖然在之後立即使用該方法似乎是正確的hide()，但它會導致不正確的結果。這是問題使用的示例：

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

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

默認設置

您可以通過修改插件的Constructor.Default對象來更改插件的默認設置：

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

方法和屬性

每個 Bootstrap 插件都公開了以下方法和靜態屬性。

方法	描述
`dispose`	銷毀元素的模態。（刪除 DOM 元素上存儲的數據）
`getInstance`	允許您獲取與 DOM 元素關聯的模式實例的靜態方法。
`getOrCreateInstance`	靜態方法，它允許您獲取與 DOM 元素關聯的模態實例，或者在未初始化的情況下創建一個新實例。

靜態屬性	描述
`NAME`	返回插件名稱。（例如`bootstrap.Tooltip.NAME`：）
`VERSION`	每個 Bootstrap 插件的版本都可以通過`VERSION`插件構造函數的屬性來訪問（例如`bootstrap.Tooltip.VERSION`：）

消毒劑

工具提示和彈出框使用我們內置的清理程序來清理接受 HTML 的選項。

默認allowList值如下：

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
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: [],
  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: []
}

如果要向此默認值添加新值，allowList可以執行以下操作：

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)

如果您想繞過我們的清理程序，因為您更喜歡使用專用庫，例如DOMPurify，您應該執行以下操作：

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

可選地使用 jQuery

Bootstrap 5 中不需要 jQuery，但仍然可以將我們的組件與 jQuery 一起使用。如果 BootstrapjQuery在對window像中檢測到，它會將我們所有的組件添加到 jQuery 的插件系統中。這允許您執行以下操作：

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

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

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

我們的其他組件也是如此。

沒有衝突

有時需要將 Bootstrap 插件與其他 UI 框架一起使用。在這些情況下，有時會發生命名空間衝突。如果發生這種情況，您可以調用.noConflict您希望恢復其值的插件。

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命名空間的事件，但您可能需要自行修復兼容性問題。

jQuery 事件

jQuery如果對像中存在jQuerywindow並且沒有data-bs-no-jquery設置屬性，Bootstrap 將檢測 jQuery <body>。如果找到 jQuery，Bootstrap 將通過 jQuery 的事件系統發出事件。所以如果你想監聽 Bootstrap 的事件，你必須使用 jQuery 方法 ( .on, .one) 而不是addEventListener.

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

禁用的 JavaScript

當 JavaScript 被禁用時，Bootstrap 的插件沒有特殊的回退。如果您關心這種情況下的用戶體驗，請使用<noscript>向您的用戶解釋情況（以及如何重新啟用 JavaScript），和/或添加您自己的自定義後備。