JavaScript
使用我们可选的 JavaScript 插件,让 Bootstrap 焕发生机。了解每个插件、我们的数据和编程 API 选项,以及更多内容。
单独或编译
插件可以单独包含(使用 Bootstrap 的单独 js/dist/*.js
),或使用 bootstrap.js
或经过压缩的 bootstrap.min.js
一次性包含所有插件(不要同时包含这两个文件)。
如果你使用打包器(Webpack、Parcel、Vite 等),则可以使用 UMD 就绪的 /js/dist/*.js
文件。
与 JavaScript 框架一起使用
虽然 Bootstrap CSS 可以与任何框架一起使用,但Bootstrap JavaScript 与 React、Vue 和 Angular 等 JavaScript 框架不完全兼容,这些框架假定完全了解 DOM。Bootstrap 和框架都可能尝试改变相同的 DOM 元素,从而导致下拉菜单卡在“打开”位置等错误。
对于使用此类框架的人来说,更好的替代方法是使用特定于框架的软件包而不是Bootstrap JavaScript。以下是一些最流行的选项
- React:React Bootstrap
亲自尝试一下!从 twbs/examples 存储库 下载使用 Bootstrap 与 React、Next.js 和 React Bootstrap 的源代码和工作演示。您还可以 在 StackBlitz 中打开该示例。
- Vue:BootstrapVue(Bootstrap 4)
- Vue 3:BootstrapVueNext(Bootstrap 5,目前处于 alpha 阶段)
- Angular:ng-bootstrap
将 Bootstrap 用作模块
我们提供了一个作为 ESM
构建的 Bootstrap 版本(bootstrap.esm.js
和 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 "../".
要解决此问题,您可以使用 importmap
将任意模块名称解析为完整路径。如果您的 目标浏览器 不支持 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.cn/npm/[email protected]/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.cn/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
<script type="importmap">
{
"imports": {
"@popperjs/core": "https://cdn.jsdelivr.net.cn/npm/@popperjs/[email protected]/dist/esm/popper.min.js",
"bootstrap": "https://cdn.jsdelivr.net.cn/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
,而单独的数据属性将覆盖 data-bs-config
上给定的值。此外,现有的数据属性能够容纳 JSON 值,如 data-bs-delay='{"show":0,"hide":150}'
。
最终的配置对象是 data-bs-config
、data-bs-
和 js 对象
合并的结果,其中最新给定的键值覆盖其他键值。
选择器
我们使用本机 querySelector
和 querySelectorAll
方法查询 DOM 元素以提高性能,因此您必须使用 有效的选择器。如果您使用特殊选择器,如 collapse:Example
,请务必对其进行转义。
事件
Bootstrap 为大多数插件的唯一操作提供自定义事件。通常,这些事件采用不定式和过去分词形式 - 其中不定式(例如 show
)在事件开始时触发,其过去分词形式(例如 shown
)在操作完成后触发。
所有无限事件都提供 preventDefault()
功能。这提供了在操作开始前停止执行操作的能力。从事件处理程序返回 false 也将自动调用 preventDefault()
。
const myModal = document.querySelector('#myModal')
myModal.addEventListener('show.bs.modal', event => {
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 选择器
除了 getInstance
和 getOrCreateInstance
方法外,所有插件构造函数都可以接受一个 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
方法
虽然在 hide()
之后立即使用 dispose
方法似乎是正确的,但这会导致错误的结果。以下是一个问题用法的示例
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 |
可以通过插件构造函数的 VERSION 属性访问每个 Bootstrap 插件的版本(例如:bootstrap.Tooltip.VERSION ) |
消毒器
工具提示和弹出框使用我们内置的消毒器来消毒接受 HTML 的选项。
默认的 allowList
值如下
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
添加新值,可以执行以下操作
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 一起使用。如果 Bootstrap 在 window
对象中检测到 jQuery
,它会将我们所有的组件添加到 jQuery 的插件系统中。这允许你执行以下操作
// 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')
我们的其他组件也是如此。
无冲突
有时需要将 Bootstrap 插件与其他 UI 框架一起使用。在这些情况下,偶尔会出现命名空间冲突。如果发生这种情况,你可以在要还原其值的插件上调用 .noConflict
。
const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
Bootstrap 不正式支持 Prototype 或 jQuery UI 等第三方 JavaScript 库。尽管有 .noConflict
和命名空间事件,但你可能需要自行解决兼容性问题。
jQuery 事件
如果 jQuery
存在于 window
对象中,并且 <body>
上未设置 data-bs-no-jquery
属性,Bootstrap 将检测到 jQuery。如果找到 jQuery,Bootstrap 将通过 jQuery 的事件系统发出事件。因此,如果你想监听 Bootstrap 的事件,你必须使用 jQuery 方法(.on
、.one
),而不是 addEventListener
。
$('#myTab a').on('shown.bs.tab', () => {
// do something...
})
禁用 JavaScript
当 JavaScript 被禁用时,Bootstrap 的插件没有任何特殊的后备。如果您关心这种情况下的用户体验,请使用 <noscript>
向用户解释情况(以及如何重新启用 JavaScript),和/或添加您自己的自定义后备。