bootstrap-v5-v6-migration

Bootstrap v5 到 v6 迁移

工作流

按顺序完成每个步骤。完成每个步骤后，先在代码库中搜索是否还有 v5 模式，再继续下一步。

• 步骤 1：更新依赖项和构建设置
• 步骤 2：重命名 CSS 类和数据属性
• 步骤 3：调整组件 HTML 结构
• 步骤 4：更新 JavaScript
• 步骤 5：更新 Sass
• 步骤 6：验证

---

步骤 1：依赖项和构建

1. 更新 package.json："bootstrap": "6.0.0-alpha.1"
2. 将 @popperjs/core 替换为 @floating-ui/dom
3. 如果使用 Datepicker，添加 peer dep vanilla-calendar-pro
4. Sass：将所有 @import 替换为 @use（不再支持 Node Sass）

bootstrap.bundle.js 包含 Floating UI 和 Vanilla Calendar Pro。独立的 bootstrap.js 会将两者作为外部 peer dependencies。直接在浏览器中加载独立构建版本时，需要使用 import map。

// v5
@import "bootstrap/scss/bootstrap";

// v6
@use "bootstrap/scss/bootstrap";

// v6 with overrides — customize CSS tokens through the token maps
@use "bootstrap/scss/bootstrap" with (
  $root-tokens: (
    --spacer: 1rem,
  )
);

通过覆盖 CSS token 映射来自定义样式——全局 token 使用 $root-tokens，各组件使用对应的 $*-tokens 映射——而不要使用旧版 Sass 标量。参见自定义 › Sass。在 Sass 中，token 名称不带前缀（例如 --spacer、--border-radius）；Bootstrap 的 dist/CDN CSS 会运行 PostCSS 来添加 --bs- 前缀（--bs-spacer），因此自行编译源码时，属性将保持无前缀状态。

---

步骤 2：CSS 类和属性重命名

响应式和状态前缀语法

v6 将断点和伪状态从中缀／后缀改为带冒号的前缀形式。同时将 xxl 重命名为 2xl。

模式： .{class}-{bp}-{value} 变为 .{bp}:{class}-{value}，而 .{class}-{bp} 变为 .{bp}:{class}

v5	v6
.d-md-none、.p-lg-3	.md:d-none、.lg:p-3
.col-md-6	.md:col-6
.row-cols-md-3	.md:row-cols-3
.offset-md-2	.md:offset-2
.g-md-3、.gx-md-3	.md:g-3、.md:gx-3
.g-col-md-4	.md:g-col-4
.container-sm	.sm:container
.navbar-expand-md	.md:navbar-expand
.offcanvas-md	.md:drawer
.table-responsive-md	.md:table-responsive
.list-group-horizontal-md	.md:list-group-horizontal
.sticky-md-top	.md:sticky-top
.vstack-md	.md:vstack
.dialog-fullscreen-sm-down	.sm-down:dialog-fullscreen
.d-print-none	.print:d-none
.opacity-50-hover	.hover:opacity-50

前缀不会标明查询类型。工具类、网格列、容器、抽屉和响应式表格使用视口查询。堆叠布局、CSS Grid 列、导航栏展开、水平列表组、卡片组和堆叠表格使用容器查询。请添加各组件文档要求的查询容器。

组件重命名

三个组件已完全重命名。请在类、数据属性、事件、JS 导入和 CSS 变量中查找并替换这些前缀。

Modal -> Dialog

范围	v5	v6
类	.modal、.modal-header/body/footer/title	.dialog、.dialog-header/body/footer/title
尺寸	.modal-sm/lg/xl/fullscreen	.dialog-sm/lg/xl/fullscreen
数据属性	data-bs-toggle="modal"、data-bs-dismiss="modal"	data-bs-toggle="dialog"、data-bs-dismiss="dialog"
JS 导出项	Modal	Dialog
事件	*.bs.modal	*.bs.dialog
CSS 变量	--modal-*	--dialog-*
body 类	<body> 上的 .modal-open	<html> 上的 .dialog-open

彻底移除 .modal-dialog 和 .modal-content 包装元素——参见步骤 3。

Offcanvas → 抽屉

范围	v5	v6
类	.offcanvas, .offcanvas-start/end/top/bottom/header/body/title	.drawer, .drawer-start/end/top/bottom/header/body/title
Data 属性	data-bs-toggle="offcanvas", data-bs-dismiss="offcanvas"	data-bs-toggle="drawer", data-bs-dismiss="drawer"
JS 导出	Offcanvas	Drawer
事件	*.bs.offcanvas	*.bs.drawer
CSS 变量	--offcanvas-*	--drawer-*
Sass	$zindex-offcanvas	$zindex-drawer

Dropdown → 菜单

范围	v5	v6
类	.dropdown-menu, .dropdown-item, .dropdown-divider, .dropdown-header	.menu, .menu-item, .menu-divider, .menu-header
Data 属性	data-bs-toggle="dropdown"	data-bs-toggle="menu"
JS 导出	Dropdown	Menu
事件	*.bs.dropdown	*.bs.menu
Sass	$zindex-dropdown	$zindex-menu

此外，请移除：.dropdown-toggle（不再需要）、.dropdown 包装元素、.dropdown-toggle-split。新标记请参阅第 3 步。

按钮和徽章变体 → 主题令牌

按颜色区分的类已由“变体 + .theme-*”组合取代。内置主题键包括 primary、accent、success、danger、warning、info、inverse 和 secondary。在同一个元素上同时应用这两个类。

v5	v6
.btn-primary	class="btn-solid theme-primary"
.btn-outline-primary	class="btn-outline theme-primary"
.alert-primary	class="alert theme-primary"
.badge.bg-primary	class="badge theme-primary"

新增按钮变体：.btn-solid、.btn-outline、.btn-subtle、.btn-text、.btn-styled、.btn-link。

在嵌套子树上使用 .theme-reset，可移除继承的 --theme-* 令牌并恢复为组件默认值。

没有 .theme-light 或 .theme-dark 类。请手动检查 v5 的浅色和深色变体，并酌情使用中性色表面工具类、颜色模式或 .theme-inverse。

占位符动画

标准加载动画请使用 .placeholder-wave。需要旧版不透明度动画时，将 .placeholder-glow 替换为 .placeholder-pulse。.placeholder-glow 仍作为兼容别名保留。

工具类重命名

v5	v6
.text-primary、.text-danger 等	.fg-primary、.fg-danger 等
.text-muted	.fg-secondary
.mh-*	.max-h-*
.mw-*	.max-w-*
.form-select	.form-control（用于 <select>）
.clearfix	.d-flow-root
.has-validation	移除（不再需要）
.lh-base	.lh-md
.text-bg-primary	class="bg-primary fg-contrast-primary"
.link-offset-*、.link-underline-*	.underline-offset-*、.underline-*

移除 .display-1 至 .display-6 和 .lead。使用 .fs-* 和 .fw-* 工具类组合出这些样式。检查 .bg-light、.bg-dark 和 .bg-body-*；请使用迁移指南中介绍的 v6 中性色表面和颜色模式。

字号类

v6 将数字比例替换为 T 恤尺码（按升序排列）。v6 的完整比例为 xs sm md lg xl 2xl 3xl 4xl 5xl 6xl。以下 rem 值是 v5 的字号，仅用于帮助你匹配各个类。

v5（字号）	v6
.fs-1 (2.5rem)	.fs-4xl
.fs-2 (2rem)	.fs-3xl
.fs-3 (1.75rem)	.fs-2xl
.fs-4 (1.5rem)	.fs-xl
.fs-5 (1.25rem)	.fs-lg
.fs-6 (1rem)	.fs-md

注意：在 v6 中，lg 及更大的字号使用流式 clamp() 值，会随视口大小在最小值和最大值之间缩放（例如，4xl 为 clamp(2.25rem, 1.75rem + 2.5vw, 3rem)）；xs/sm/md 则保持固定。因此字号不会与 v5 完全一致——此映射保留的是相对比例，而非精确的 rem 值。

间距刻度

键 2-5 的值已更改。要保留 v5 间距：.p-2（0.5rem）-> .p-3，.p-3（1rem）-> .p-5，.p-4（1.5rem）-> .p-7，.p-5（3rem）-> .p-12。

键	v5	v6
2	0.5rem	0.375rem
3	1rem	0.5rem
4	1.5rem	0.75rem
5	3rem	1rem
6-12	—	1.25rem 到 3rem，步长为 0.25rem

负外边距仅限于 .ms--1、.ms--2、.me--1、.me--2（-0.25rem、-0.5rem）。v5 的 .m*-n* 类（例如 .mt-n1、.ms-n3）已移除：请使用其中一种，或自定义样式。

表单验证

v5	v6
<form> 上的 .needs-validation	<form> 上的 data-bs-validate
通过 JS 添加 .was-validated	移除——:user-invalid 会处理
<div class="valid-tooltip">	<div class="tooltip valid-tooltip">
<div class="invalid-tooltip">	<div class="tooltip invalid-tooltip">

---

第 3 步：结构性 HTML 更改

这些组件的标记发生了根本性变化，而不仅仅是类名重命名。

对话框（原为 Modal）

移除 .modal-dialog 和 .modal-content 包装元素。改用单个 <dialog> 元素。背景遮罩现在由原生 ::backdrop 提供。

<div class="modal" tabindex="-1">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title">Title</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
      </div>
      <div class="modal-body">Content</div>
      <div class="modal-footer">
        <button class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
      </div>
    </div>
  </div>
</div>


<dialog class="dialog" id="exampleDialog">
  <div class="dialog-header">
    <h5 class="dialog-title">Title</h5>
    <button type="button" class="btn-close" data-bs-dismiss="dialog" aria-label="Close"></button>
  </div>
  <div class="dialog-body">Content</div>
  <div class="dialog-footer">
    <button class="btn-solid theme-secondary" data-bs-dismiss="dialog">Close</button>
  </div>
</dialog>

抽屉（原为 Offcanvas）

使用原生 <dialog> 元素。仅重命名为 <div class="drawer"> 并不起作用。

<div class="offcanvas offcanvas-start" id="menu">...</div>


<dialog class="drawer drawer-start" id="menu">...</dialog>

对于响应式导航栏，将 data-bs-toggle="collapse" 更改为 data-bs-toggle="drawer"。将 .collapse.navbar-collapse 替换为包含 .drawer-header 和 .drawer-body 的 <dialog class="drawer">。将 .navbar-expand-md 重命名为 .md:navbar-expand，并移除 .navbar-light 或 .navbar-dark。

手风琴

将 Collapse JS 替换为原生 <details>/<summary>。name 属性可创建互斥分组（替代 data-bs-parent）。在 <summary> 内添加 .accordion-icon SVG。移除 .accordion-button 和 .accordion-collapse。新增修饰符：.accordion-sm 用于紧凑的内边距和字体，.accordion-gap 用于将项目间隔开，呈现为独立的圆角卡片。

<div class="accordion" id="myAccordion">
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button" data-bs-toggle="collapse" data-bs-target="#collapseOne">
        Item 1
      </button>
    </h2>
    <div id="collapseOne" class="accordion-collapse collapse show" data-bs-parent="#myAccordion">
      <div class="accordion-body">Content</div>
    </div>
  </div>
</div>


<div class="accordion">
  <details class="accordion-item" name="myAccordion" open>
    <summary class="accordion-header">
      Item 1
      <svg class="accordion-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="m2 5 6 6 6-6"/></svg>
    </summary>
    <div class="accordion-body">Content</div>
  </details>
</div>

卡片

检查卡片标记以及任何自定义卡片 CSS。v6 更改了卡片边框、布局和若干辅助类。

• .card 负责背景、外边框、圆角、阴影和高度。页眉和页脚仅绘制分隔边框。
• .card-body 是可选的。现在它是一个弹性列，会移除直接子元素的块级外边距，并使用 --card-body-gap 控制间距。添加 .flex-row 可将主体设为水平布局。
• 保留卡片内列表组上的 .list-group-flush。不要添加 .card-list；此类不可用。
• .card-title 和 .card-text 不再添加样式。仅将它们用作项目钩子。.card-subtitle 仍会缩小副标题上方的间距。
• .card-link 已移除。需要链接行时，请使用普通链接和 flex 或 gap 工具类。
• 水平卡片请使用 .card-row。新的视觉变体请使用 .card-subtle 或 .card-translucent。
• 卡片组现在使用容器查询。请在父元素上添加 .contains-inline，否则卡片会保持堆叠状态。

菜单（原为 Dropdown）

移除 .dropdown 包装元素和 .dropdown-toggle。将 <ul><li><a> 展平为 <div><a>。切换按钮和 .menu 是同级元素。

<div class="dropdown">
  <button class="btn dropdown-toggle" data-bs-toggle="dropdown">Menu</button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Other</a></li>
  </ul>
</div>


<button class="btn-solid theme-secondary" data-bs-toggle="menu">Menu</button>
<div class="menu">
  <a class="menu-item" href="#">Action</a>
  <hr class="menu-divider">
  <a class="menu-item" href="#">Other</a>
</div>

关闭按钮

标记不变——.btn-close 仍是空元素。不要添加子 SVG（这会导致图标重复渲染）。变化在内部：v6 使用 CSS mask（--btn-close-icon）在 background-color: currentcolor 上绘制图标，因此按钮现在会继承当前文本 color，而不是使用固定图像。

<button type="button" class="btn-close" aria-label="Close"></button>

由于图标使用 currentcolor，v5 的 .btn-close-white 变体已移除——要获得浅色关闭按钮，请设置文本颜色（例如，将它放在深色的 .theme-* 上下文中，或添加 .fg-* / color 工具类）。

复选框

直接在 <input> 上应用 .check。不需要包装元素，也不需要内联 SVG——标记是应用于 ::before 的 CSS mask。单选按钮（.radio）遵循相同模式。开关仍使用 .switch 包装输入元素。

<div class="form-check">
  <input class="form-check-input" type="checkbox" id="check1">
  <label class="form-check-label" for="check1">Check me</label>
</div>


<div class="form-field">
  <input type="checkbox" id="check1" class="check">
  <label for="check1">Check me</label>
</div>

单选按钮和开关的对应写法：

<div class="form-field">
  <input type="radio" id="radio1" class="radio">
  <label for="radio1">Pick me</label>
</div>


<div class="form-field">
  <div class="switch">
    <input type="checkbox" id="switch1" role="switch" switch>
  </div>
  <label for="switch1">Toggle me</label>
</div>

切换按钮

输入现在嵌套在标签内。将 .btn-check 放在标签上。无需 id/for。

<input type="checkbox" class="btn-check" id="toggle1" autocomplete="off">
<label class="btn btn-outline-primary" for="toggle1">Toggle</label>


<label class="btn-check btn-solid theme-primary">
  <input type="checkbox" autocomplete="off">
  Toggle
</label>

范围滑块

.form-range 现在是一个包装器和 JavaScript 钩子。将该类从输入移到包装器上，并为输入添加 .form-range-input。

<input type="range" class="form-range">


<div class="form-range">
  <input type="range" class="form-range-input">
</div>

面包屑

为 <a> 元素添加 .breadcrumb-link。在各项之间添加空的 .breadcrumb-divider 分隔符（取代 ::before 伪元素）。空分隔符会通过 CSS 遮罩渲染默认的尖括号。默认的底部外边距已移除（v5 使用 $spacer）。

<ol class="breadcrumb">
  <li class="breadcrumb-item"><a href="#">Home</a></li>
  <li class="breadcrumb-item active">Library</li>
</ol>


<ol class="breadcrumb">
  <li class="breadcrumb-item"><a class="breadcrumb-link" href="#">Home</a></li>
  <li class="breadcrumb-divider"></li>
  <li class="breadcrumb-item"><a class="breadcrumb-link active" href="#">Library</a></li>
</ol>

---

第 4 步：JavaScript

仅支持 ESM

所有 dist 文件现在都是 ES 模块。不再提供 UMD 包，也不再提供 window.bootstrap 全局变量。

<script src="bootstrap.bundle.min.js"></script>


<script type="module" src="bootstrap.bundle.min.js"></script>

将全局命名空间访问替换为导入：

// v5 — global namespace
const tooltip = bootstrap.Tooltip.getOrCreateInstance(el)

// v6 — explicit import
import { Tooltip } from './bootstrap.bundle.min.js'

const tooltip = Tooltip.getOrCreateInstance(el)

添加 type="module" 后，数据 API 初始化仍会自动运行。请在此技能中应用组件和数据属性的重命名。打包工具导入（import { X } from 'bootstrap'）仍按原方式工作。

捆绑版构建包含 Floating UI 和 Vanilla Calendar Pro。独立版构建需要已安装的对等依赖，或浏览器导入映射。

重命名的 JS 导出

v5	v6
Modal	Dialog
Offcanvas	Drawer
Dropdown	Menu

Popper → Floating UI

将 @popperjs/core 替换为 @floating-ui/dom。将 Tooltip、Popover 和 Menu 的 popperConfig 选项重命名为 floatingConfig。

生命周期方法返回 promise

show()、hide()、toggle() 和 close() 现在会返回一个 promise，该 promise 会在过渡结束时解析。你可以使用 await，无需监听 shown.bs.* / hidden.bs.*。这些事件仍会触发。

当指针悬停在提示框上，或焦点位于提示框内时，悬停和焦点提示框会保持打开（WCAG 1.4.13）。按下 Escape，或移开触发元素和提示框上的指针及焦点，即可将其隐藏。

弹出式日期选择器会在与外部交互、按下 Escape，或焦点离开输入框和日历时关闭。

TypeScript 声明

Bootstrap 的源码现在使用 TypeScript 编写。该软件包包含类型声明，因此请移除 @types/bootstrap。深层 .js 导入会解析到编译后的 js/dist 文件。

已移除

• jQuery 支持
• bootstrap.esm.js / bootstrap.esm.min.js — 请使用 bootstrap.js
• js/index.umd.js

验证 JS

// v5
document.querySelectorAll('.needs-validation')
form.classList.add('was-validated')

// v6
document.querySelectorAll('form[data-bs-validate]')
// Remove the was-validated line entirely

---

第 5 步：Sass

重命名的文件

v5	v6
_variables.scss	_config.scss
_variables-dark.scss	已移除（合并到 _theme.scss）
_maps.scss	已移除
_placeholders.scss	_placeholder.scss
_spinners.scss	_spinner.scss
_form-check.scss	_check.scss、_radio.scss、_switch.scss
mixins/_forms.scss	mixins/_form-validation.scss
forms/_form-variables.scss	已移除
vendor/_rfs.scss	已移除

重命名的变量和函数

v5	v6
$grid-breakpoints	$breakpoints
$border-radius、$border-radius-sm/lg/xl/xxl、$border-radius-pill	已移除 — 请参阅下方的圆角比例
$text-muted	使用次要颜色
$hr-bg-color	$hr-border-color
$hr-height	$hr-border-width
$zindex-dropdown	$zindex-menu
$zindex-offcanvas	$zindex-drawer
$form-validation-states	$validation-states
$btn-close-white-filter	已移除 — 图标使用 currentcolor
$enable-negative-margins	已移除 — 始终会生成负外边距；请自定义 $negative-spacers
add() / subtract()	calc()
breakpoint-infix()	breakpoint-prefix()（返回 "md\:"，而不是 "-md"）
$infix（在循环 mixin 中）	$prefix
$prefix（CSS 变量前缀）	已移除 — 请改用 PostCSS

圆角比例

$border-radius-* 变量已移除。v6 使用单个基础变量 $radius: .5rem 和 $radii 映射（键为 0–9，例如 5: $radius、9: $radius * 2），并公开为 --radius-0–--radius-9 令牌（以及 --radius-pill）。.rounded-* 工具类现在覆盖 0–9，且对应的值与 v5 不同；若要保持相同的圆角程度，请将类名数字调大（例如 .rounded-1 → .rounded-3，.rounded-3 → .rounded-5）。请覆盖基础变量或映射条目，而不是旧的各尺寸变量：

// $radius lives in _config.scss, so configure that module before loading Bootstrap
@use "bootstrap/scss/config" with (
  $radius: .375rem // scales the whole map
);
@use "bootstrap/scss/bootstrap";

已移除（无替代项）

• $nested-kbd-font-weight
• $enable-dark-mode — 始终会编译深色模式
• $enable-validation-icons
• $enable-caret、$caret-width、$caret-vertical-align、$caret-spacing
• $accordion-button-focus-border-color、$tooltip-arrow-color
• $popover-arrow-color、$popover-arrow-outer-color
• $alert-bg-scale、$alert-border-scale、$alert-color-scale
• $list-group-item-bg-scale、$list-group-item-color-scale
• $carousel-dark-indicator-active-bg、$carousel-dark-control-icon-filter
• $dropdown-header-padding
• 所有 *-focus-box-shadow 变量 — 请使用带有 --focus-ring-* CSS 自定义属性的 focus-ring() 混入
• RFS 混入 — 请使用 clamp() 实现响应式尺寸
• create-css-vars() 混入
• 插入符混入（caret()、caret-down()、caret-up()、caret-end()、caret-start()）— 请改为在切换按钮标记中添加图标
• 文本颜色工具类映射中的 muted、black-50、white-50

工具 API

已移除 css-var、css-variable-name 和 local-vars 选项。请改用 property 映射和 variables。

主题映射合并

$theme-colors、$theme-bgs、$theme-fgs、$theme-borders、$badge-variants 及其他全局映射使用 defaults()。通过 @use ... with () 传入你要更改的键即可。将键设为 null 可移除该键。嵌套的主题颜色映射会合并一层 — 若要更改某个角色，请传入整个子映射。

根令牌会在 :root, :host 上输出。如果使用 Shadow DOM，请在 :host 上重复设置 :root 覆盖项。

---

重构后的行为与新增组件

除了上述重命名外，还有一些改动会影响 v5 项目的行为或可用功能。请查看文档了解完整的标记和选项。

轮播 — 基于 CSS scroll-snap 重构

标记（.carousel → .carousel-inner → .carousel-item）和 JS API（next/prev/to/cycle/pause、slide/slid 事件）保持不变，但有几项改动：

• ride → autoplay（布尔值，选择启用）。 data-bs-ride="carousel" 改为 data-bs-autoplay="true"；{ ride: 'carousel' } 改为 { autoplay: true }。默认值为 autoplay: false，因此 v5 中会自动切换的轮播现在会保持静止，除非你选择启用自动播放。与自动播放中的轮播交互现在会永久停止自动播放（WCAG 2.2.2）。
• wrap → ends。 wrap: true → ends: "wrap"（或新的默认值 "loop"）；wrap: false → ends: "stop"。通过 data-bs-ends 设置。已移除 touch 选项（由原生滚动处理）。
• 已移除的类： .carousel-control-prev/next（请组合使用 .btn-icon + data-bs-slide + .carousel-icon-prev/next）、.carousel-caption（请使用自定义标记）、.carousel-dark（请使用 data-bs-theme="dark"）、.carousel-stacked（现在为默认行为），以及过渡用的 .carousel-item-start/end/next/prev。叠加控件现在需要 .carousel-overlay。控件图标类已重命名：.carousel-control-prev-icon → .carousel-icon-prev（以及 -next）。

ScrollSpy — 基于 IntersectionObserver 重建

data-bs-spy="scroll" 标记和 activate.bs.scrollspy 事件保持不变，但检测现在由激活线驱动（不再轮询滚动位置），选项也有所变化：

• 移除了已弃用的 offset 和 method 选项（自 v5.1.3 起弃用）——不再解析。
• 新增 topMargin（默认值为 12%）——以 % 或 px 值设置激活线距滚动根容器顶部的位置（例如 96px，使其位于固定导航栏下方）。这是日常使用的主要选项；请用它代替 rootMargin。
• rootMargin 现在是高级覆盖选项（默认值为 null，原先为 '0px 0px -25%'）；设置后会优先于 topMargin，并直接传递给观察器。
• threshold 的默认值从 [0.1, 0.5, 1] 改为 [0]。
• 启用 smoothScroll 时，点击链接现在会恢复 URL 哈希（history.replaceState），并在滚动结束后将焦点移至目标位置（改善键盘和辅助技术导航体验）。
• 目标 id 现在使用 getElementById 解析，因此包含点、冒号、斜杠或百分号编码的 ID 无需手动转义即可使用。

Collapse — 简化状态和过渡

• 移除依赖 .collapsing 的选择器和测试。Collapse 现在会切换 .show，并使用原生尺寸插值。
• 将触发器的 .collapsed 选择器替换为 [aria-expanded="false"]。
• 移除 toggle 构造函数选项。初始化时需要更改状态，请调用 show() 或 hide()。

新增组件（v5 中不存在）

组件	触发器 / 钩子	用途
Combobox	data-bs-toggle="combobox"	基于 Menu 构建的可筛选/自动完成选择框
Chip / Chip input	.chip、.chip-input（data-bs-chips）	标签 / 令牌及交互式输入
Datepicker	data-bs-toggle="datepicker"	日期选择器（同级依赖 vanilla-calendar-pro）
Range	.form-range（+ data-bs-bubble、刻度）	带数值气泡的增强型范围滑块
Strength	data-bs-strength	密码强度计
OTP input	data-bs-otp	一次性验证码输入框
Nav overflow	包裹 .nav 的 .nav-overflow 容器	将溢出的导航项折叠到菜单中
Toggler	data-bs-toggle="toggler"	通用类名/属性切换器
Submenu	.submenu（位于 Menu 内）	嵌套菜单（submenuTrigger、submenuDelay）
Stepper	.stepper	多步骤工作流（仅 CSS）
Avatar	.avatar	支持尺寸、状态和 .avatar-stack 的头像（仅 CSS）
Form adorn	.form-adorn	输入框上的图标/文本装饰（仅 CSS）
Prose	.prose / .not-prose	富文本排版范围控制（仅 CSS）

已移除 / 更改的内部实现

• 已移除 util/backdrop.js、util/focustrap.js 和 util/scrollbar.js。 Dialog 和 Drawer 使用原生 <dialog> 元素，它提供背景遮罩（::backdrop）、焦点陷阱和惰性顶层；现在通过 CSS（:root.dialog-open）锁定 body 滚动。如果你直接导入了 bootstrap/js/src/util/backdrop、.../focustrap 或 .../scrollbar，这些模块已不存在。
• CSS @layer。 组件样式现在封装在级联层（colors, theme, config, root, reboot, layout, content, forms, components, custom, helpers, utilities）中。不属于任何层的作者 CSS 现在无论源顺序如何，优先级都高于 Bootstrap——如果你的 v5 覆盖样式依赖特异性或加载顺序，请重新检查。
• 已移除 --bs-*-rgb 变量。 $*-rgb Sass 变量和 --bs-*-rgb 自定义属性均已移除。请将 rgba(var(--bs-primary-rgb), .5) 替换为 color-mix(in oklab, var(--bs-primary), transparent 50%)（或直接使用颜色）。

---

第 6 步：验证

1. 构建项目并修复所有编译错误。
2. 搜索残留的 v5 模式：
   • modal 类/属性（应为 dialog）
   • offcanvas（应为 drawer）
   • dropdown（应为 menu）
   • d-md-、d-lg-、col-md- 等（应使用 md: 前缀语法）
   • btn-primary、btn-outline-（应使用 .btn-solid .theme-*）
   • .text-primary、.text-danger（应为 .fg-*）
   • Sass 中的 @import（应为 @use）
   • form-select（应为 form-control）
   • was-validated、needs-validation（应为 data-bs-validate）
   • popperConfig（应为 floatingConfig）
   • form-check（应为 check、radio 或 switch）
   • var(--bs-*-rgb) / rgba(var(--bs-…-rgb)（已移除——请使用 color-mix()）
   • $border-radius Sass 变量（已移除——请使用 $radius / $radii / --radius-*）
   • .btn-close 内的子 <svg>（应为空——图标使用 CSS 遮罩）
   • .btn-close-white（已移除——请改为设置文本 color）
   • <div class="drawer">（必须是原生 <dialog class="drawer">）
   • data-bs-ride（已更名为 data-bs-autoplay）；轮播图选项 wrap:（现为 ends:）
   • .carousel-control-prev/next、.carousel-caption、.carousel-dark、.carousel-stacked（均已移除）
   • .fs-1–.fs-6（应为 .fs-4xl … .fs-md）
   • .link-offset-* / .link-underline-*（现为 .underline-offset-* / .underline-*）
   • ScrollSpy 的 offset / method 选项（已移除——请使用 topMargin）
   • .check 内联的 SVG（图标使用输入框上的 CSS 遮罩）
   • $theme-colors 全映射替换（v6 通过 defaults() 合并）
   • .collapsing、.collapsed 触发器选择器，以及 Collapse 的 toggle 选项
   • 响应式堆叠、CSS Grid、导航栏、列表组、卡片组，以及没有查询容器的堆叠式表格
3. 在浏览器中测试——v6 要求支持 oklch() 和 color-mix()。