bootstrap-overview

Bootstrap 5.3 概述

Bootstrap 5.3.8 是一个功能强大的前端框架，可用于构建响应式、移动优先的网站。本技能涵盖安装、项目设置和基础概念。

快速开始选项

CDN（最快设置方式）

对于原型设计或简单项目，可使用 CDN 链接。在 <head> 中引入 CSS，并在 </body> 结束标签前引入 JS：

<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">


<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI" crossorigin="anonymous"></script>

除非单独管理 Popper，否则始终使用 bootstrap.bundle.min.js（包含 Popper.js）。

包管理器安装

npm：

npm install [email protected]

yarn：

yarn add [email protected]

pnpm：

pnpm add [email protected]

Bun：

bun add [email protected]

Composer（PHP）：

composer require twbs/bootstrap:5.3.8

NuGet（.NET）：

Install-Package bootstrap -Version 5.3.8

安装后，在 JavaScript 中导入：

import 'bootstrap/dist/css/bootstrap.min.css';
import 'bootstrap/dist/js/bootstrap.bundle.min.js';
// Or import specific components
import { Modal, Tooltip } from 'bootstrap';

ES 模块用法

若要在不使用打包工具的情况下，在浏览器中原生使用 ESM，请通过 importmap 使用 bootstrap.esm.min.js：

<script type="importmap">
{
  "imports": {
    "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/esm/popper.min.js",
    "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
  }
}
</script>
<script type="module">
  import * as bootstrap from 'bootstrap'
  // Use bootstrap components
</script>

对于较旧的浏览器，请引入 es-module-shims polyfill。

入门模板

每个 Bootstrap 页面都需要以下最简结构：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap Demo</title>
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
  </head>
  <body>
    <h1>Hello, Bootstrap!</h1>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI" crossorigin="anonymous"></script>
  </body>
</html>

关键要求：

• 使用 <!doctype html> 声明以确保正确渲染
• 添加带有 width=device-width, initial-scale=1 的响应式视口 meta 标签
• 在 <head> 中加载 CSS，并在 </body> 前加载 JavaScript

构建工具集成

对于生产应用，请将 Bootstrap 与构建工具集成，以实现摇树优化和性能优化。

Vite 设置

npm create vite@latest my-project -- --template vanilla
cd my-project
npm install bootstrap @popperjs/core
npm install -D sass

在 main.js 中导入：

import './scss/styles.scss';
import * as bootstrap from 'bootstrap';

创建 src/scss/styles.scss：

// Import Bootstrap
@import "bootstrap/scss/bootstrap";

请参阅 references/build-tools.md，了解 Parcel 和 Webpack 设置指南。

Ruby on Rails 8 设置

Rails 8 默认使用 Propshaft 作为资源管线。有三种集成方式：

方式 1：Importmaps + bootstrap gem（无需 Node.js）：

bundle add bootstrap -v "~> 5.3.8"
bundle add dartsass-rails
bin/rails dartsass:install

方式 2：cssbundling-rails（完整 Node.js）：

rails new myapp --css bootstrap
# Or for existing apps:
bundle add cssbundling-rails
bin/rails css:install:bootstrap

方式 3：仅使用 CDN——直接将 CDN 链接添加到布局中。

请参阅 references/rails-setup.md，了解完整的 Rails 8 集成指南，包括 Turbo/Stimulus 模式、表单辅助方法和 Bootstrap Icons。

JavaScript 组件

Bootstrap 5 组件可以通过两种方式初始化：

数据属性（无需 JavaScript）

<button type="button" class="btn btn-primary"
        data-bs-toggle="modal" data-bs-target="#myModal">
  Open Modal
</button>

编程式初始化

// Get element
const myModal = document.getElementById('myModal');

// Create instance
const modal = new bootstrap.Modal(myModal, {
  keyboard: false,
  backdrop: 'static'
});

// Use methods
modal.show();
modal.hide();
modal.toggle();
modal.dispose();

组件方法模式

所有组件都遵循统一的模式：

• getInstance() - 获取现有实例
• getOrCreateInstance() - 获取或创建实例
• dispose() - 销毁实例并清理
• 组件专属方法（show、hide、toggle 等）

请参阅 references/javascript-api.md，了解完整的 JavaScript API，包括所有组件的事件、方法和选项。

框架注意事项

Bootstrap JavaScript 与 React、Vue 或 Angular 并非完全兼容——Bootstrap 和框架都可能尝试修改相同的 DOM 元素，从而导致错误。对于这些框架，请使用专用包：

• React：React Bootstrap
• Vue 3：BootstrapVueNext
• Angular：ng-bootstrap

Bootstrap CSS 可与任何框架配合使用，不会出现问题。

无障碍

Bootstrap 开箱即提供无障碍组件，但正确实现仍是开发者的责任。了解 Bootstrap 的无障碍功能有助于确保符合 WCAG 2.2 标准。

无障碍功能要点

视觉隐藏内容：

使用 .visually-hidden 隐藏视觉内容，同时让屏幕阅读器仍可读取：

<p class="text-danger">
  <span class="visually-hidden">Error: </span>
  This field is required
</p>

使用 .visually-hidden-focusable 创建在键盘聚焦时显示的跳过链接：

<a class="visually-hidden-focusable" href="#main-content">
  Skip to main content
</a>

颜色对比度注意事项：

Bootstrap 的默认颜色在某些情境下可能不符合 WCAG 对比度要求：

• 文本需要 4.5:1 的对比度（WCAG AA）
• 大号文本（18pt+）需要 3:1 的对比度
• 非文本元素（图标、边框）需要 3:1 的对比度

务必测试颜色组合。在浅色背景上使用默认的 .text-muted 时，可能需要调整以符合要求。必要时可考虑使用 .text-body 或 .text-body-emphasis 来提高对比度。

减少动态效果支持：

Bootstrap 遵循 prefers-reduced-motion 媒体查询：

@media (prefers-reduced-motion: reduce) {
  /* Transitions and animations are disabled or minimized */
}

对于偏好减少动态效果的用户，轮播、模态框和折叠等组件会自动减少或禁用动画。

ARIA 实现

交互式组件包含适当的 ARIA 属性：

<div class="accordion-item">
  <h2 class="accordion-header">
    <button class="accordion-button" type="button"
            data-bs-toggle="collapse"
            data-bs-target="#collapseOne"
            aria-expanded="true"
            aria-controls="collapseOne">
      Section Title
    </button>
  </h2>
  <div id="collapseOne" class="accordion-collapse collapse show"
       aria-labelledby="headingOne">
    <div class="accordion-body">Content here</div>
  </div>
</div>

对于由 JavaScript 驱动的组件，Bootstrap 会自动处理 aria-expanded、aria-controls 和 aria-hidden。

焦点管理

Bootstrap 会妥善管理交互式组件的焦点：

• 模态框会将焦点限制在对话框内
• 下拉菜单关闭时会恢复焦点
• 工具提示和弹出框支持键盘访问

对于自定义实现，可使用 Bootstrap 的焦点陷阱工具，或手动管理焦点。

RFS（响应式字号）

RFS 是 Bootstrap 的响应式缩放引擎，可根据视口尺寸自动调整字号、外边距、内边距和其他属性。

RFS 的工作原理

RFS 会生成结合 rem 单位与视口宽度（vw）的 calc() 函数，实现流畅缩放：

// Input
.title {
  @include font-size(4rem);
}

// Output
.title {
  font-size: calc(1.525rem + 3.3vw);
}
@media (min-width: 1200px) {
  .title {
    font-size: 4rem;
  }
}

属性会在最小与最大视口尺寸之间平滑缩放，然后在更大的屏幕上锁定为指定值。

使用 RFS 混入

字号：

.heading {
  @include font-size(2.5rem);
}

其他属性：

.card {
  @include padding(2rem);
  @include margin(1.5rem);
  @include rfs(1rem, border-radius);
}

RFS 函数

对于媒体查询中的属性或复杂计算：

.responsive-element {
  @include media-breakpoint-down(lg) {
    padding: rfs-fluid-value(2rem);
    font-size: rfs-fluid-value(1.125rem);
  }
}

配置

RFS 的行为通过 Sass 变量控制：

$rfs-base-value: 1.25rem;        // Minimum font size
$rfs-unit: rem;                   // Output unit
$rfs-breakpoint: 1200px;          // Max viewport for scaling
$rfs-factor: 10;                  // Scaling intensity

较低的 $rfs-factor 值（例如 5）会带来更明显的缩放效果；较高的值（例如 15）则会减弱效果。默认值为 10。

RTL（从右向左）支持

Bootstrap 5 内置 RTL 支持。启用方法：

1. 在 <html> 元素上设置 dir="rtl"
2. 使用 RTL 样式表：

<html lang="ar" dir="rtl">
  <head>
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.rtl.min.css" rel="stylesheet" integrity="sha384-CfCrinSRH2IR6a4e6fy2q6ioOX7O6Mtm1L9vRvFZ1trBncWmMePhzvafv7oIcWiW" crossorigin="anonymous">
  </head>
</html>

逻辑属性（start/end）会取代方向属性（left/right）。

浏览器支持

Bootstrap 5.3 仅支持现代浏览器：

浏览器	支持级别
Chrome	最新 2 个版本
Firefox	最新 2 个版本
Safari	最新 2 个版本
Edge	最新 2 个版本
iOS Safari	最新 2 个版本
Android Chrome	最新 2 个版本

不支持： Internet Explorer（任何版本）。Bootstrap 5 完全移除了对 IE 的支持，因此无需提供回退方案即可使用 CSS 自定义属性、flexbox 和 grid 等现代 CSS 功能。

移动设备注意事项

Bootstrap 采用移动优先设计。所有组件都适合触控，且具有合适的点击目标（交互元素至少为 44x44 像素）。请在实际设备上进行测试，因为浏览器 DevTools 无法完全模拟触控交互、滚动行为或性能特征。

CSS 变量

Bootstrap 5.3 大量使用 CSS 自定义属性：

:root {
  --bs-blue: #0d6efd;
  --bs-primary: #0d6efd;
  --bs-body-font-family: system-ui, -apple-system, sans-serif;
  --bs-body-font-size: 1rem;
  --bs-body-line-height: 1.5;
}

可在根级别或组件级别覆盖：

.my-component {
  --bs-primary: #custom-color;
}

依赖项

Bootstrap 5.3 的 JavaScript 需要：

• Popper.js（包含在 bootstrap.bundle.js 中）——下拉菜单、弹出框、工具提示及任何具有定位功能的组件都需要它
• 不依赖 jQuery（Bootstrap 5 已移除）

选择合适的构建包：

• bootstrap.bundle.js ——包含 Popper.js（大多数项目推荐使用）
• bootstrap.js ——不含 Popper.js（适用于单独管理 Popper 或不使用定位组件的场景）

文件结构

通过 npm 安装时：

node_modules/bootstrap/
├── dist/
│   ├── css/
│   │   ├── bootstrap.css
│   │   ├── bootstrap.min.css
│   │   ├── bootstrap.rtl.css
│   │   └── bootstrap.rtl.min.css
│   └── js/
│       ├── bootstrap.js
│       ├── bootstrap.min.js
│       ├── bootstrap.bundle.js
│       └── bootstrap.bundle.min.js
└── scss/
    ├── bootstrap.scss
    ├── _variables.scss
    └── ...

可用的 CSS 构建版本：

文件	内容
bootstrap.css	完整框架（默认）
bootstrap-grid.css	仅包含网格系统和 flex 工具类
bootstrap-utilities.css	仅包含工具类
bootstrap-reboot.css	仅包含 Reboot 规范化样式

每个变体都提供 .min.css（压缩版）和 .rtl.css（从右向左）版本。

核心概念

移动优先

Bootstrap 采用移动优先设计。基础样式面向移动设备，并通过媒体查询在更大的断点处应用响应式增强。这种方式意味着：

• 从移动端布局开始，为更大的屏幕添加复杂性
• 使用 min-width 媒体查询（样式会在断点及以上生效）
• 除非要专门针对较小屏幕，否则避免使用 max-width 查询

盒模型

Bootstrap 全局设置 box-sizing: border-box，取代默认的 content-box。这样可确保内边距不会影响元素最终计算出的宽度，简化尺寸计算。这可能与第三方小部件（例如 Google Maps）冲突。必要时可使用 .selector { box-sizing: content-box; } 覆盖。

Reboot

Bootstrap 的 Reboot 提供具有明确风格的 CSS 规范化样式，以确保跨浏览器渲染一致。详情请参阅 bootstrap-content 技能。

断点

默认响应式断点：

• xs：<576px（默认，无 infix）
• sm：≥576px
• md：≥768px
• lg：≥992px
• xl：≥1200px
• xxl：≥1400px

容器系统

三种容器类型：

• .container - 固定宽度，支持响应式（宽度会在每个断点处变化）
• .container-fluid - 始终为全宽（所有断点下均为 100%）
• .container-{breakpoint} - 在达到断点前为全宽，之后为固定宽度

<div class="container">Fixed-width responsive</div>
<div class="container-fluid">Always 100% width</div>
<div class="container-lg">100% until lg, then fixed</div>

容器提供水平内边距（默认值为 --bs-gutter-x: 1.5rem），并在视口内居中显示内容。

其他资源

参考文件

• references/build-tools.md - Vite、Parcel 和 Webpack 的完整配置指南
• references/rails-setup.md - Ruby on Rails 8 与 Propshaft、Turbo 和 Stimulus 的集成
• references/javascript-api.md - 完整的 JavaScript 组件 API 参考
• references/vite-setup.md - 详细的 Vite 项目结构和配置

示例文件

• examples/starter-template.html - 基础 HTML 入门模板
• examples/rtl-starter.html - 启用 RTL 并包含阿拉伯语内容的入门模板
• examples/rails-application-layout.html.erb - 包含 Bootstrap 的 Rails 8 应用布局
• examples/rails-bootstrap-form.html.erb - 使用 Bootstrap 样式的 Rails 表单辅助方法
• examples/rails-flash-messages.html.erb - 作为 Bootstrap 提示框的 Flash 消息
• examples/rails-navbar-partial.html.erb - 适用于 Rails 的响应式导航栏局部模板
• examples/rails-turbo-modal.html.erb - 兼容 Turbo 的 Bootstrap 模态框

相关技能

• bootstrap-customize - Sass 变量、主题设置、色彩模式
• bootstrap-layout - 网格系统、容器、断点详解
• bootstrap-content - Reboot 和排版