JavaScript
使用我們基於 jQuery 構建的可選 JavaScript 插件將 Bootstrap 帶入生活。了解每個插件、我們的數據和編程 API 選項等。
單獨或編譯
插件可以單獨包含(使用 Bootstrap 的 individual js/dist/*.js
),或者使用bootstrap.js
或縮小後的所有插件bootstrap.min.js
(不要同時包含兩者)。
如果您使用捆綁器(Webpack、Rollup…),您可以使用/js/dist/*.js
已準備好 UMD 的文件。
依賴項
一些插件和 CSS 組件依賴於其他插件。如果您單獨包含插件,請確保在文檔中檢查這些依賴項。另請注意,所有插件都依賴於 jQuery(這意味著 jQuery 必須包含在插件文件之前)。請諮詢我們package.json
以了解支持的 jQuery 版本。
我們的下拉菜單、彈出框和工具提示也依賴於Popper.js。
數據屬性
幾乎所有的 Bootstrap 插件都可以通過 HTML 單獨啟用和配置數據屬性(我們使用 JavaScript 功能的首選方式)。確保僅在單個元素上使用一組數據屬性(例如,您不能從同一個按鈕觸發工具提示和模式。)
但是,在某些情況下,可能需要禁用此功能。要禁用數據屬性 API,請取消綁定命名空間的文檔上的所有事件,data-api
如下所示:
$(document).off('.data-api')
或者,要針對特定插件,只需將插件的名稱作為命名空間與 data-api 命名空間一起包含,如下所示:
$(document).off('.alert.data-api')
選擇器
目前要查詢 DOM 元素,我們使用本地方法querySelector
,querySelectorAll
出於性能原因,您必須使用有效的選擇器。如果您使用特殊的選擇器,例如: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
插件構造函數的屬性來訪問。例如,對於工具提示插件:
$.fn.tooltip.Constructor.VERSION // => "4.6.2"
禁用 JavaScript 時沒有特殊的回退
當 JavaScript 被禁用時,Bootstrap 的插件不會特別優雅地回退。如果您關心這種情況下的用戶體驗,請使用<noscript>
向您的用戶解釋情況(以及如何重新啟用 JavaScript),和/或添加您自己的自定義後備。
第三方庫
Bootstrap 不正式支持第三方 JavaScript 庫,如 Prototype 或 jQuery UI。儘管有.noConflict
命名空間的事件,但您可能需要自行修復兼容性問題。
實用程序
所有 Bootstrap 的 JavaScript 文件都依賴於util.js
並且必須與其他 JavaScript 文件一起包含。如果您使用的是已編譯(或縮小)bootstrap.js
的,則無需包含它——它已經存在。
util.js
包括實用功能和事件的基本幫助程序transitionEnd
以及 CSS 轉換模擬器。其他插件使用它來檢查 CSS 過渡支持並捕獲懸掛過渡。
消毒劑
工具提示和彈出框使用我們內置的清理程序來清理接受 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)
}
})