设计思路 · Bootstrap 6.0 中文文档

Sass 与 CSS

Bootstrap 6 带来了新的理念：结合使用 Sass 与 CSS，针对你的具体需求构建和定制项目。概括来说：

Sass 用于程序化配置——包括函数、循环、mixin 等生成式结构。
CSS 用于视觉定制——使用 CSS 变量控制颜色、间距、排版等视觉属性。

之前的几个大版本把 Sass 同时用于程序化配置和视觉定制，而 CSS 变量只是额外增加了一层更复杂、也更不完整的次要机制。v6 对此做了大幅改进。

此外，我们使用 PostCSS 为 CSS 变量加上 bs- 前缀（前缀处理），并按需为 CSS 属性添加浏览器厂商前缀。

Sass

Sass 用于以下用途：

导入（@use 和 @forward）各个可编译为 CSS 的样式表。
用 mixin 和函数管理重复的代码片段。
切换 $enable-smooth-scroll、$enable-reduced-motion 等全局选项。
通过 Sass map、循环等配置并生成组件变体（主题色、尺寸等）。
为颜色的每个色调和明暗批量生成 CSS 变量。
管理组件 token 列表（例如 $alert-tokens），并将其应用到特定类。
为工具类 API 提供支持，以自定义和生成工具类。

CSS

虽然你可以用 Sass 定制 Bootstrap 的外观，但现在更推荐尽可能使用 CSS 变量，包括在使用 Sass 时。我们这样使用 CSS：

自定义单个全局 token 和组件 token，例如 --bs-border-radius、--bs-alert-padding-x 等。
使用 Sass 的 with (...tokens) 语法自定义 token 值，以覆盖默认值。
混合颜色，为每个色相生成浅色和深色变体。
使用 calc() 根据另一个 token 或 CSS 变量的值计算动态值。

示例

下面是我们如何结合 Sass 和 CSS 来定制 Bootstrap。Sass 帮助我们管理功能，并提供生成式 token；CSS 则让我们可以自定义单个 token 和值。在几乎所有的组件中，我们都会建立一个“token” Sass map，其中的 token 实际上就是 CSS 变量。然后使用这个 map 在组件类上生成 CSS 自定义属性。

例如，警告框组件有一个 $alert-tokens map，用于在 .alert 类上生成 CSS 自定义属性。

SCSS

          $alert-tokens: (
  --alert-padding-x: 2rem,
  --alert-border-radius: 1rem,
  // …
);

.alert {
  @include tokens($alert-tokens);
  // …
}

在实践中，这意味着你可以使用 Sass 的模块系统，在构建时为特定组件甚至全局覆盖 CSS 变量。

SCSS

          @use "../node_modules/bootstrap/scss/bootstrap" with (
  // Manage global options
  $enable-smooth-scroll: true,

  // Modify global tokens
  $root-tokens: (
    --border-radius: .25rem,
    --spacer: 1.5rem,
  ),

  // Modify component tokens
  $alert-tokens: (
    --alert-padding-x: calc(var(--spacer) * 2),
    --alert-border-radius: 1rem,
  ),
);

下面是一个只能用 Sass 实现的示例，用 CSS 很难达到同样效果。以下代码会从 button-variants map 中移除 text 和 subtle 变体，并覆盖 button-sizes map，使其只包含 sm 和 lg 尺寸。

SCSS

          @use "../node_modules/bootstrap/scss/bootstrap" with (
  // Modify button sizes to remove default `xs` size
  $button-sizes: ("sm", "lg"),

  // Remove default `text` and `subtle` button variants with `null`
  $button-variants: (
    "text": null,
    "subtle": null,
  ),
);

下面是一个只用纯 CSS 定制编译后 CSS 变量的示例。所有使用 var(--bs-border-radius) 的地方，都会被替换为 .25rem。

CSS

          :root {
  --border-radius: .25rem;
  --spacer: 1.5rem;
}

现代基础

Bootstrap 采用了一些重要的全局样式和设置，用于统一浏览器样式、支持响应式移动优先设计，并提供一个现代化基础。

响应式设计

响应式网页设计是指构建一个能响应其所在设备视口大小的网站。实现方式是使用范围媒体查询，根据视口大小对网站应用不同样式。

CSS

          @media (width < 768px) {
  .container {
    max-width: 100%;
  }
}

Bootstrap 附带多个响应式层级（或断点），让你可以从小型移动设备到大型桌面屏幕逐层叠加样式。这为你提供了一种非常灵活且强大的方式，构建可针对任意尺寸设备优化的网站。

HTML5 文档类型

Bootstrap 要求使用 HTML5 文档类型。否则，你会看到一些怪异且不完整的样式。

HTML

          <!doctype html>
<html lang="en">
  …
</html>

Viewport meta

Bootstrap 采用移动优先的开发方式：先针对移动设备优化代码，再通过 CSS 媒体查询按需放大组件。为确保所有设备都能正确渲染并支持触摸缩放，请在 <head> 中添加响应式 viewport meta 标签。

HTML

          <!doctype html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    …
  </head>
  <body>
    …
  </body>
</html>

你可以在快速开始中看到一个实际示例。

Box-sizing

为了让 CSS 尺寸计算更直接，我们把全局 box-sizing 从 content-box 改为 border-box。这样可以确保 padding 不影响元素的最终计算宽度。

在极少数需要覆盖它的情况下，可以使用类似下面的写法：

CSS

          .your-selector {
  box-sizing: content-box;
}

在 CSS Tricks 中进一步了解盒模型与尺寸计算。

Reboot

为改善跨浏览器渲染，我们使用 Reboot 修正不同浏览器和设备之间的不一致，同时为常见 HTML 元素提供带有一定主张的重置样式。

浏览器支持

你可以在我们的 .browserslistrc 文件中查看支持的浏览器范围及版本。各版本下限的原因，以及这些下限为我们提供和未提供的平台特性，请参阅浏览器与设备。

PLAINTEXT

last 2 major versions
not dead
unreleased versions

Chrome >= 130
Edge >= 130
Firefox >= 132
iOS >= 18.0
Safari >= 18.0

not and_uc > 0
not and_qq > 0
not kaios > 0
not op_mini all

如果你通过 npm 安装 Bootstrap，也可以在本地 node_modules/bootstrap/.browserslistrc 找到这个文件。

我们使用 Autoprefixer 通过 CSS 前缀处理目标浏览器支持，它使用 Browserslist 管理浏览器版本。有关如何把这些工具集成到项目中，请查阅它们的文档。

指导原则

除了 Bootstrap 做了什么，这里还说明为什么这样做——我们在 Web 上构建的哲学。概括来说，指导我们思路的原则如下：

组件应当是响应式且移动优先的
组件应基于一个基础类构建，并通过修饰类扩展
组件状态应遵循统一的 z-index 层级
优先使用 HTML 和 CSS 实现，而不是 JavaScript
优先使用工具类，而不是自定义样式
避免强制严格的 HTML 结构要求（直接子元素选择器）

这些规则无法总是被严格遵循，但我们会尽可能遵守。

响应式

Bootstrap 的样式是移动优先的——我们随着视口增大而添加样式，而不是在视口缩小时覆盖样式。并非每个组件都必须完全响应式，但这种方式可以减少 CSS 覆盖。

我们使用范围媒体查询（例如 width >= 768px）在特定断点应用样式，并一直延续到更大的断点。例如，.d-none 从 min-width: 0 一直生效到无限大；而 .md:d-none 则从中等断点开始生效。

类

除了 Reboot，我们尽量只把类用作选择器。在可行的情况下，避免使用类型选择器和多余的父选择器，以获得更大的灵活性。

组件通常由一个基础类提供共享的属性值对。例如 .btn、.btn-solid 和 .theme-primary。我们用 .btn 承载 display、padding、border-width 等所有通用样式，再用 .btn-solid.theme-primary 这样的变体和主题修饰类添加更多样式。

这降低了复杂度、精简了代码，也使系统更易扩展。

z-index 层级

Bootstrap 中使用两套 z-index 层级——组件内部元素和浮层组件。

Bootstrap 中有些组件通过重叠元素来避免双重边框，而无需修改 border 属性，例如按钮组、输入框组和分页。这些组件共用一套从 0 到 3 的标准 z-index 层级，与我们期望的用户优先级一致。

0 用于默认状态（初始状态，实际上不会设置）
1 用于 :hover，最低，因为它表示用户意图，但几乎任何元素都可能被悬停。
2 用于 :active/.active，第二高，因为它们表示状态。
3 用于 :focus，最高，因为获得焦点的元素处于视野中并受到用户关注。

使用浮层的组件也有一套预定义的 z-index 层级，从 1000 开始。这个起始值是随意选定的，用来在我们的样式和你项目的自定义样式之间留出一点缓冲。

scss/_config.scss

$zindex-levels: (
  n1: -1,
  0: 0,
  1: 1,
  2: 2,
  3: 3,
  menu: 1000,
  sticky: 1010,
  fixed: 1020,
  drawer: 1030,
  dialog: 1040,
  popover: 1050,
  tooltip: 1060,
  toast: 1070,
);

每个浮层组件都会略微提高其 z-index，以便遵循常见的 UI 原则，让用户聚焦或悬停的元素始终保持在视野中。例如，对话框会阻塞文档（除了对话框中的操作，你无法进行其他操作），因此我们把它放在导航栏之上。

在我们的 z-index 布局页面中了解更多。

优先使用 HTML 和 CSS，而非 JS

只要可能，我们就优先使用 HTML 和 CSS，而不是 JavaScript——它们对所有经验水平的用户都更友好，在浏览器中也更快。这也是为什么我们的一等 JavaScript API 是 data 属性：它让你可以多写 HTML、少写 JavaScript。更多内容请参阅JavaScript 概览。

我们的样式建立在浏览器基础行为之上。例如，虽然你可以把 .btn 放到几乎任何元素上，但我们更推荐具有语义价值的 <button> 和 <a>。对于表单验证，我们通过 data-bs-validate 限定样式作用域，并使用 :user-invalid 伪类，让反馈只在用户交互后出现，而不是在页面初始加载时就出现。

工具类

工具类——像 .d-block 对应 display: block; 这样的单一、不可变的属性值对——有助于减少 CSS 体积并提升性能。它们加快 HTML 编写，并通过把重复的属性值对合并为可复用的类来减少自定义 CSS。我们尽量在可能时使用它们，而不是额外编写 CSS。

代码约定

Code Guide记录了我们的 HTML 和 CSS 编写方式——涵盖格式、默认值、属性顺序等。我们通过 Stylelint 和我们的开源配置来执行这些标准。

社区

通过这些有用的资源，了解 Bootstrap 的最新开发进展并与社区交流。

阅读并订阅官方 Bootstrap 博客。
在GitHub Discussions 中提问和探索。
在社区 Discord或 Bootstrap subreddit中讨论、提问等。
在 IRC 上与其他 Bootstrapper 聊天：irc.libera.chat 服务器，#bootstrap 频道。
实现方面的帮助可以在 Stack Overflow 上找到（标签为 bootstrap-5）。
在 npm 上发布 Bootstrap 相关包的开发者应使用 bootstrap 关键字，以便被搜索到。

你也可以在 X 上关注 @getbootstrap，获取最新动态和精彩音乐视频。