bootstrap-components

Bootstrap 5.3 组件

Bootstrap 提供可直接使用的 UI 组件，用于构建界面。本技能涵盖所有主要组件及其使用模式、JavaScript 初始化要求和无障碍最佳实践。

JavaScript 初始化概览： 有些组件仅使用数据属性即可运行，其他组件则需要初始化 JavaScript。下方标记为 需要 JS 的组件必须显式初始化才能正常运行。

组件	需要 JS 初始化	仅使用数据属性
Tooltip	是	否
Popover	是	否
Toast	是（用于显示）	否
Scrollspy	可选	是
Modal	可选	是
Carousel	可选	是
Collapse	可选	是
Dropdown	可选	是

交互组件

这些组件需要或适合使用 JavaScript。详细代码示例、JavaScript API 和无障碍指南请参阅 references/interactive-components.md。

Accordion

可折叠内容面板，一次显示一个分区。使用 .accordion 容器，其子元素为 .accordion-item，并包含 .accordion-header 和 .accordion-collapse。移除 data-bs-parent，即可允许同时展开多个面板。使用 .accordion-flush 可创建无边框变体。

Carousel

带有可选控件和指示器的图片幻灯片。使用 .carousel.slide 容器，其中的 .carousel-inner 包含 .carousel-item 幻灯片。添加 .carousel-control-prev/.carousel-control-next 以进行导航。使用 data-bs-ride="carousel" 可自动播放。会自动遵循 prefers-reduced-motion 设置。

Collapse

通过平滑动画切换内容的可见性。在触发器上使用 data-bs-toggle="collapse"，并通过 data-bs-target 指向 .collapse 元素。使用 .collapse-horizontal 可按宽度折叠。使用类选择器（.multi-collapse）可指定多个元素。

Dropdowns

可切换的上下文菜单，用于放置链接和操作。使用 .dropdown 容器，其中包含 .dropdown-toggle 按钮和 .dropdown-menu 列表。方向变体：.dropup、.dropend、.dropstart。添加 .dropdown-menu-dark 可使用深色主题。内置键盘导航。

Modal

覆盖页面并锁定焦点的对话框。使用 data-bs-toggle="modal"，并通过 data-bs-target 指向 .modal 元素。尺寸：.modal-sm、.modal-lg、.modal-xl。修饰类：.modal-dialog-centered、.modal-dialog-scrollable。使用 data-bs-backdrop="static" 可阻止点击外部区域关闭对话框。

Offcanvas

从视口边缘滑入的隐藏侧边栏。位置：.offcanvas-start（左侧）、.offcanvas-end（右侧）、.offcanvas-top、.offcanvas-bottom。使用 data-bs-scroll="true" 可允许滚动主体内容。使用 data-bs-backdrop="static" 可创建常驻侧边栏。

Popovers

需要初始化 JS 和 Popper.js。 点击或悬停时触发的富内容浮层。使用 data-bs-toggle="popover"，并设置 data-bs-title 和 data-bs-content。通过 new bootstrap.Popover(el) 初始化，也可批量初始化全部元素：document.querySelectorAll('[data-bs-toggle="popover"]').forEach(el => new bootstrap.Popover(el))。位置：top、right、bottom、left。使用 bootstrap.bundle.js（包含 Popper），或在 bootstrap.js 之前单独引入 Popper。

Scrollspy

根据滚动位置自动更新导航。在可滚动容器上使用 data-bs-spy="scroll"，并通过 data-bs-target 指向导航。使用 data-bs-root-margin 控制激活阈值。容器需要设置 tabindex="0"，以便仅使用键盘的用户无需鼠标即可聚焦并滚动容器。

Toasts

显示时需要初始化 JS。 轻量、可关闭的通知。使用 .toast-container 定位并堆叠通知。通过 new bootstrap.Toast(el) 初始化，然后调用 .show()。选项：autohide: true、delay: 5000。可通过容器定位类设置位置。

工具提示

需要初始化 JS 和 Popper.js。 悬停时显示简短说明。使用 data-bs-toggle="tooltip"，并搭配 data-bs-title（首选）或 title 属性。使用 new bootstrap.Tooltip(el) 初始化，或批量初始化所有元素：document.querySelectorAll('[data-bs-toggle="tooltip"]').forEach(el => new bootstrap.Tooltip(el))。位置：top、right、bottom、left。禁用按钮上的工具提示需要使用带有 tabindex="0" 的 <span> 或 <div> 包装，以支持键盘访问。使用 bootstrap.bundle.js（包含 Popper），或在 bootstrap.js 之前单独引入 Popper。

静态组件

这些组件主要通过 CSS 和 HTML 实现。详细代码示例和无障碍指南请参阅 references/static-components.md。

提示框

提供上下文反馈消息。使用带有 role="alert" 的 .alert.alert-{color}。颜色：primary、secondary、success、danger、warning、info、light、dark。使用 .alert-link 设置链接样式。添加 .alert-dismissible 和关闭按钮，即可关闭提示框。

徽章

用于标签、计数和状态指示。对 <span> 使用 .badge.bg-{color}。使用 .rounded-pill 设置胶囊形状。使用 .position-absolute 工具类定位通知徽章。添加 .visually-hidden 文本，为屏幕阅读器提供上下文。

面包屑

用于指示导航层级。将 <ol class="breadcrumb"> 放在 <nav aria-label="breadcrumb"> 中。对 <li> 元素使用 .breadcrumb-item。使用 .active 和 aria-current="page" 标记当前页面。通过 CSS 变量 --bs-breadcrumb-divider 自定义分隔符。

按钮

交互式按钮元素。基本样式：.btn.btn-{color}。轮廓样式：.btn-outline-{color}。尺寸：.btn-lg、.btn-sm。全宽：使用 .d-grid 包装。状态：disabled 属性、.active 类。操作使用 <button>，导航使用 <a>。

按钮组

将相关按钮组合在一起。使用带有 role="group" 和 aria-label 的 .btn-group。垂直排列：.btn-group-vertical。工具栏：使用带有 role="toolbar" 的 .btn-toolbar 包装。尺寸：.btn-group-lg、.btn-group-sm。

卡片

灵活的内容容器。结构：.card > .card-body > .card-title、.card-text。可选元素：.card-header、.card-footer、.card-img-top/.card-img-bottom。网格布局：使用 .row.row-cols-{n}，其中 .col 内包含 .card.h-100，以保持高度一致。

关闭按钮

通用关闭按钮。使用带有 aria-label="Close" 的 .btn-close。白色变体：.btn-close-white。通过 data-bs-dismiss="alert|modal|offcanvas|toast" 指定关闭目标。

列表组

将一系列内容项呈现为列表。使用 .list-group > .list-group-item。可交互：添加 .list-group-item-action。无边框：.list-group-flush。水平排列：.list-group-horizontal。颜色：.list-group-item-{color}。

导航栏

响应式导航页眉。使用 .navbar.navbar-expand-{breakpoint}。包含 .navbar-brand、.navbar-toggler、.navbar-collapse。位置：.fixed-top、.fixed-bottom、.sticky-top。主题：data-bs-theme="dark"（.navbar-light 在 v5.3 中已弃用）。

导航和选项卡

带有视觉样式的基础导航。样式：.nav-tabs、.nav-pills、.nav-underline。布局：.nav-fill（等宽）、.nav-justified（全宽）、.flex-column（垂直）。对于选项卡内容，使用带有 role="tab" 按钮和 role="tabpanel" 面板的 role="tablist"。

分页

用于分页内容的导航。使用 <nav aria-label="..."> > .pagination > .page-item > .page-link。尺寸：.pagination-lg、.pagination-sm。对齐方式：.justify-content-center、.justify-content-end。使用 .active 和 aria-current="page" 标记当前页。

占位符

用于指示加载状态。使用 .placeholder 跨度元素，并设置列宽（.col-6）。动画：用 .placeholder-glow 或 .placeholder-wave 包装。尺寸：.placeholder-lg、.placeholder-sm、.placeholder-xs。为占位符容器添加 aria-hidden="true"。

进度条

任务的进度指示器。使用 .progress 包装器，并在其中放置 .progress-bar。通过 style="width: X%" 设置宽度。变体：.progress-bar-striped、.progress-bar-animated。颜色：.bg-{color}。添加 ARIA 属性：role="progressbar"、aria-valuenow、aria-valuemin、aria-valuemax。

加载动画

加载指示器。类型：.spinner-border（旋转）、.spinner-grow（脉动）。尺寸：.spinner-border-sm、.spinner-grow-sm。颜色：.text-{color}。添加 role="status" 和 .visually-hidden 加载文本。

常见问题与提示

需要 JavaScript 初始化的组件

如果没有显式的 JavaScript 初始化，工具提示和弹出框将无法使用。与模态框、下拉菜单和轮播图（通过数据属性即可使用）不同，这些组件必须初始化：

// Initialize all tooltips
document.querySelectorAll('[data-bs-toggle="tooltip"]')
  .forEach(el => new bootstrap.Tooltip(el));

// Initialize all popovers
document.querySelectorAll('[data-bs-toggle="popover"]')
  .forEach(el => new bootstrap.Popover(el));

Toast 也需要通过 JavaScript 显示——它们默认隐藏，必须通过程序调用 toast.show() 来显示。

工具提示/弹出框定位问题

如果工具提示或弹出框的位置不正确、被裁切，或在复杂布局（输入组、按钮组、表格、模态框）中表现异常，请使用 container: 'body'：

// Append to body to avoid rendering issues
new bootstrap.Tooltip(el, { container: 'body' });
new bootstrap.Popover(el, { container: 'body' });

对于模态框内的弹出框，将 container 设置为模态框主体，以保持焦点限制在模态框内：

new bootstrap.Popover(el, { container: '.modal-body' });

模态框最佳实践

语义化标题：Bootstrap 建议在语义上使用 <h1> 作为模态框标题（模态框代表其自身的文档上下文）。使用 .fs-5 等字体大小工具类控制视觉效果，同时保持正确的标题层级。

自动聚焦的变通方案：由于 HTML5 语义，HTML autofocus 属性在 Bootstrap 模态框中不起作用。若要在模态框打开时聚焦输入框：

myModal.addEventListener('shown.bs.modal', () => {
  document.getElementById('myInput').focus();
});

嵌套模态框：Bootstrap 一次仅支持一个模态框。不支持嵌套模态框，而且这被视为不佳的用户体验。如果需要多个对话框，请先关闭当前模态框，再打开另一个。

动态内容高度：动态更改模态框主体内容并影响其高度后，调用 modal.handleUpdate() 以重新调整模态框的位置。

跨组件模式

带表单的模态框：将表单验证反馈放在模态框主体内。成功提交后，调用 modal.hide()，并可选择显示 Toast 通知。

Toast 堆叠：使用 .toast-container 和定位工具类（.position-fixed.bottom-0.end-0.p-3），以保持 Toast 位置一致。多个 Toast 会自动堆叠。

带 offcanvas 的导航栏：对于移动端导航，将 .navbar 与 offcanvas 结合使用，创建滑动菜单。在导航栏切换按钮上使用 data-bs-toggle="offcanvas" 而不是 collapse，以采用不同的 UX 模式。

网格中的卡片：使用 .row.row-cols-{n}，并在 .col 中放置 .card.h-100，即可创建能响应断点的等高卡片网格。

其他资源

参考文件

• references/components-reference.md - 所有组件类的速查表
• references/css-custom-properties.md - 用于运行时组件主题设置的 CSS 自定义属性
• references/interactive-components.md - JavaScript 依赖型组件的详细文档
• references/static-components.md - CSS/HTML 组件的详细文档

示例文件

• examples/accordion-patterns.html - 手风琴和常见问题解答模式
• examples/alert-patterns.html - 提示变体、可关闭提示和实时区域模式
• examples/badge-button-patterns.html - 徽章、按钮、按钮组和关闭按钮
• examples/breadcrumb-patterns.html - 使用自定义分隔符和图标的面包屑导航
• examples/card-grid-patterns.html - 响应式卡片网格布局
• examples/carousel-patterns.html - 轮播图实现模式
• examples/collapse-patterns.html - 折叠、水平折叠和多目标模式
• examples/dropdown-patterns.html - 下拉菜单、分割按钮和表单下拉菜单
• examples/list-group-patterns.html - 列表组、可操作项和选项卡集成
• examples/modal-patterns.html - 模态对话框模式
• examples/navbar-patterns.html - 导航栏布局
• examples/offcanvas-patterns.html - 画布外侧边栏模式
• examples/pagination-patterns.html - 分页变体、对齐方式和响应式模式
• examples/placeholder-patterns.html - 卡片、列表和表格的加载骨架屏模式
• examples/popovers-tooltips-patterns.html - 工具提示和弹出框模式（需要初始化 JS）
• examples/progress-spinner-patterns.html - 进度条和加载旋转指示器
• examples/scrollspy-patterns.html - 导航栏、列表组和文档中的滚动监听模式
• examples/tabs-patterns.html - 选项卡导航模式
• examples/toasts-patterns.html - Toast 通知模式（需要初始化 JS）