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

版本號碼

每個 Bootstrap jQuery 外掛程式的版本都可以透過外掛程式建構函式的 VERSION 屬性存取。例如，對於 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)
  }
})