跳到主要內容 跳到文檔導航
in English

JavaScript

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

單獨或編譯

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

如果您使用捆綁器(Webpack、Rollup…),您可以使用/js/dist/*.js已準備好 UMD 的文件。

使用 Bootstrap 作為模塊

我們提供了一個構建為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>

不兼容的插件

由於瀏覽器的限制,我們的一些插件,即 Dropdown、Tooltip 和 Popover 插件,不能在<script>帶有類型的標籤中使用,module因為它們依賴於 Popper。有關該問題的更多信息,請參見此處

依賴項

一些插件和 CSS 組件依賴於其他插件。如果您單獨包含插件,請確保在文檔中檢查這些依賴項。

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

還想使用 jQuery?這是可能的!

Bootstrap 5 被設計為在沒有 jQuery 的情況下使用,但仍然可以將我們的組件與 jQuery 一起使用。如果 BootstrapjQuery在對window中檢測到,它會將我們所有的組件添加到 jQuery 的插件系統中;這意味著您將能夠$('[data-bs-toggle="tooltip"]').tooltip()啟用工具提示。我們的其他組件也是如此。

數據屬性

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

選擇器

目前要查詢 DOM 元素,我們使用本地方法querySelectorquerySelectorAll出於性能原因,您必須使用有效的選擇器。如果您使用特殊的選擇器,例如:collapse:Example一定要轉義它們。

活動

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

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

var myModal = document.getElementById('myModal')

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

jQuery 事件

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

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

程序化 API

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

var myModalEl = document.getElementById('myModal')

var modal = new bootstrap.Modal(myModalEl) // initialized with defaults
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard

如果你想獲得一個特定的插件實例,每個插件都會公開一個getInstance方法。要直接從元素中檢索它,請執行以下操作bootstrap.Popover.getInstance(myPopoverEl)

構造函數中的 CSS 選擇器

您還可以使用 CSS 選擇器作為第一個參數而不是 DOM 元素來初始化插件。目前,該querySelector方法可以找到插件的元素,因為我們的插件僅支持單個元素。

var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')

異步函數和轉換

所有編程 API 方法都是異步的,並在轉換開始但在結束之前返回給調用者。

為了在轉換完成後執行一個動作,您可以監聽相應的事件。

var myCollapseEl = document.getElementById('myCollapse')

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

此外,對過渡組件的方法調用將被忽略

var myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', function (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 !!

默認設置

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

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

沒有衝突(僅當您使用 jQuery 時)

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

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

版本號

每個 Bootstrap 插件的版本都可以通過VERSION插件構造函數的屬性來訪問。例如,對於工具提示插件:

bootstrap.Tooltip.VERSION // => "5.1.3"

禁用 JavaScript 時沒有特殊的回退

當 JavaScript 被禁用時,Bootstrap 的插件不會特別優雅地回退。如果您關心這種情況下的用戶體驗,請使用<noscript>向您的用戶解釋情況(以及如何重新啟用 JavaScript),和/或添加您自己的自定義後備。

第三方庫

Bootstrap 不正式支持第三方 JavaScript 庫,如 Prototype 或 jQuery UI。儘管有.noConflict命名空間的事件,但您可能需要自行修復兼容性問題。

消毒劑

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

默認allowList值如下:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var 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可以執行以下操作:

var 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
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

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

var yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})