bootstrap-v5-v6-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bootstrap v5 to v6 Migration

Bootstrap v5 至 v6 迁移

Workflow

工作流程

Step 1: Dependencies & Build

步骤1：依赖与构建

Update

package.json

"bootstrap": "6.0.0-alpha.1"

Replace
```
@popperjs/core
```
with
```
@floating-ui/dom
```
If using Datepicker, add peer dep
```
vanilla-calendar-pro
```
Sass: replace all
```
@import
```
with
```
@use
```
(Node Sass is no longer supported)

bootstrap.bundle.js

includes Floating UI and Vanilla Calendar Pro. Standalone

bootstrap.js

leaves both peer dependencies external. Direct browser loading of the standalone build needs an import map.

scss

// 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,
  )
);

Customize by overriding the CSS token maps —

$root-tokens

for global tokens and each component's

$*-tokens

map — rather than legacy Sass scalars. See Customize › Sass. Token names are written unprefixed in Sass (e.g.

--spacer

--border-radius

); Bootstrap's dist/CDN CSS runs PostCSS to add the

--bs-

prefix (

--bs-spacer

), so when you compile the source yourself the properties stay unprefixed.

更新

package.json

：

"bootstrap": "6.0.0-alpha.1"

将
```
@popperjs/core
```
替换为
```
@floating-ui/dom
```
如果使用 Datepicker，添加 peer 依赖
```
vanilla-calendar-pro
```
Sass：将所有
```
@import
```
替换为
```
@use
```
（不再支持 Node Sass）

bootstrap.bundle.js

包含 Floating UI 和 Vanilla Calendar Pro。独立版本的

bootstrap.js

则将这两个 peer 依赖设为外部引入。直接在浏览器中加载独立构建版本需要使用 import map。

scss

// 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 令牌映射进行自定义——全局令牌使用

$root-tokens

，每个组件有对应的

$*-tokens

映射——而非传统的 Sass 标量变量。参见自定义 › Sass。令牌名称在 Sass 中不带前缀（例如

--spacer

、

--border-radius

）；Bootstrap 的发布版/CDN CSS 会通过 PostCSS 添加

--bs-

前缀（即

--bs-spacer

），因此如果你自行编译源码，这些属性将保持无前缀状态。

Step 2: CSS Class & Attribute Renames

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

Responsive & state prefix syntax

响应式与状态前缀语法

v6 moves breakpoints and pseudo-states from infix/suffix to prefix with colon. Also renames

xxl

2xl

Pattern:

.{class}-{bp}-{value}

becomes

.{bp}:{class}-{value}

and

.{class}-{bp}

becomes

.{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`

The prefix does not identify the query type. Utilities, grid columns, containers, drawers, and responsive tables use viewport queries. Stacks, CSS Grid columns, navbar expansion, horizontal list groups, card groups, and stacked tables use container queries. Add the query container that each component’s documentation requires.

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`

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

Component renames

组件重命名

Three components have been fully renamed. Find-and-replace these prefixes across classes, data attributes, events, JS imports, and CSS variables.

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

Modal -> Dialog

Scope	v5	v6
Classes	`.modal` , `.modal-header/body/footer/title`	`.dialog` , `.dialog-header/body/footer/title`
Sizes	`.modal-sm/lg/xl/fullscreen`	`.dialog-sm/lg/xl/fullscreen`
Data attrs	`data-bs-toggle="modal"` , `data-bs-dismiss="modal"`	`data-bs-toggle="dialog"` , `data-bs-dismiss="dialog"`
JS export	`Modal`	`Dialog`
Events	`*.bs.modal`	`*.bs.dialog`
CSS vars	`--modal-*`	`--dialog-*`
Body class	`.modal-open` on `<body>`	`.dialog-open` on `<html>`

Remove

.modal-dialog

and

.modal-content

wrappers entirely — see Step 3.

范围	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 -> Drawer

Scope	v5	v6
Classes	`.offcanvas` , `.offcanvas-start/end/top/bottom/header/body/title`	`.drawer` , `.drawer-start/end/top/bottom/header/body/title`
Data attrs	`data-bs-toggle="offcanvas"` , `data-bs-dismiss="offcanvas"`	`data-bs-toggle="drawer"` , `data-bs-dismiss="drawer"`
JS export	`Offcanvas`	`Drawer`
Events	`*.bs.offcanvas`	`*.bs.drawer`
CSS vars	`--offcanvas-*`	`--drawer-*`
Sass	`$zindex-offcanvas`	`$zindex-drawer`

范围	v5	v6
类名	`.offcanvas` , `.offcanvas-start/end/top/bottom/header/body/title`	`.drawer` , `.drawer-start/end/top/bottom/header/body/title`
数据属性	`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 -> Menu

Scope	v5	v6
Classes	`.dropdown-menu` , `.dropdown-item` , `.dropdown-divider` , `.dropdown-header`	`.menu` , `.menu-item` , `.menu-divider` , `.menu-header`
Data attrs	`data-bs-toggle="dropdown"`	`data-bs-toggle="menu"`
JS export	`Dropdown`	`Menu`
Events	`*.bs.dropdown`	`*.bs.menu`
Sass	`$zindex-dropdown`	`$zindex-menu`

Also remove:

.dropdown-toggle

(no longer needed),

.dropdown

wrapper,

.dropdown-toggle-split

. See Step 3 for new markup.

范围	v5	v6
类名	`.dropdown-menu` , `.dropdown-item` , `.dropdown-divider` , `.dropdown-header`	`.menu` , `.menu-item` , `.menu-divider` , `.menu-header`
数据属性	`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。

Button & badge variants -> theme tokens

按钮与徽章变体 -> 主题令牌

Per-color classes are replaced by variant +

.theme-*

composition. Built-in theme keys are

primary

accent

success

danger

warning

info

inverse

, and

secondary

. Apply both classes to the same element.

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"`

New button variants:

.btn-solid

.btn-outline

.btn-subtle

.btn-text

.btn-styled

.btn-link

Use

.theme-reset

on a nested subtree to drop inherited

--theme-*

tokens and return to component defaults.

There are no

.theme-light

.theme-dark

classes. Review v5 light and dark variants manually. Use neutral surface utilities, color modes, or

.theme-inverse

as appropriate.

每种颜色对应的独立类已被替换为变体 +

.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 animations

占位符动画

Use

.placeholder-wave

for the standard loading animation. Replace

.placeholder-glow

with

.placeholder-pulse

when you want the old opacity animation.

.placeholder-glow

remains as a compatibility alias.

标准加载动画使用

.placeholder-wave

。如果需要旧的透明度动画，请将

.placeholder-glow

替换为

.placeholder-pulse

。

.placeholder-glow

作为兼容别名仍然保留。

Utility class renames

工具类重命名

v5	v6
`.text-primary` , `.text-danger` , etc.	`.fg-primary` , `.fg-danger` , etc.
`.text-muted`	`.fg-secondary`
`.mh-*`	`.max-h-*`
`.mw-*`	`.max-w-*`
`.form-select`	`.form-control` (on `<select>` )
`.clearfix`	`.d-flow-root`
`.has-validation`	Remove (no longer needed)
`.lh-base`	`.lh-md`
`.text-bg-primary`	`class="bg-primary fg-contrast-primary"`
`.link-offset-` , `.link-underline-`	`.underline-offset-` , `.underline-`

Remove

.display-1

through

.display-6

and

.lead

. Compose their styles with

.fs-*

and

.fw-*

utilities. Review

.bg-light

.bg-dark

, and

.bg-body-*

; use the v6 neutral surfaces and color modes described in the migration guide.

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 中性表面和颜色模式。

Font size classes

字体大小类

v6 replaces the numeric scale with t-shirt sizes (ascending). The full v6 scale is

xs sm md lg xl 2xl 3xl 4xl 5xl 6xl

. The rem values below are the v5 sizes, shown only to help you match each class.

v5 (size)	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`

Note: in v6,

lg

and larger are fluid
clamp()
values that scale with the viewport between a min and a max (e.g.

4xl

clamp(2.25rem, 1.75rem + 2.5vw, 3rem)

);

xs

sm

md

stay fixed. So sizes won't match v5 exactly — the mapping preserves the relative scale, not the precise rem.

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 值。

Spacer scale

间距刻度

Keys 2-5 have changed values. To preserve v5 spacing:

.p-2

(0.5rem) ->

.p-3

.p-3

(1rem) ->

.p-5

.p-4

(1.5rem) ->

.p-7

.p-5

(3rem) ->

.p-12

Key	v5	v6
2	`0.5rem`	`0.375rem`
3	`1rem`	`0.5rem`
4	`1.5rem`	`0.75rem`
5	`3rem`	`1rem`
6-12	—	`1.25rem` through `3rem` , in `0.25rem` steps

键 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`

Form validation

表单验证

v5	v6
`.needs-validation` on `<form>`	`data-bs-validate` on `<form>`
`.was-validated` via JS	Remove — `:user-invalid` handles it
`<div class="valid-tooltip">`	`<div class="tooltip valid-tooltip">`
`<div class="invalid-tooltip">`	`<div class="tooltip invalid-tooltip">`

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">`

Step 3: Structural HTML Changes

步骤3：HTML 结构变更

These components have fundamentally new markup, not just class renames.

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

Dialog (was Modal)

Dialog（原 Modal）

Remove the

.modal-dialog

and

.modal-content

wrappers. Use a single

<dialog>

element. The backdrop is now native

::backdrop

html

<!-- v5 -->
<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>

<!-- v6 -->
<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>

移除

.modal-dialog

和

.modal-content

包装器。使用单个

<dialog>

元素。背景现在使用原生的

::backdrop

。

html

<!-- v5 -->
<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>

<!-- v6 -->
<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>

Drawer (was Offcanvas)

Drawer（原 Offcanvas）

Use a native

<dialog>

element. A renamed

<div class="drawer">

does not work.

html

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

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

For responsive navbars, change

data-bs-toggle="collapse"

data-bs-toggle="drawer"

. Replace

.collapse.navbar-collapse

with a

<dialog class="drawer">

that contains

.drawer-header

and

.drawer-body

. Rename

.navbar-expand-md

.md:navbar-expand

, and remove

.navbar-light

.navbar-dark

使用原生

<dialog>

元素。重命名后的

<div class="drawer">

无法正常工作。

html

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

<!-- v6 -->
<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

。

Accordion

Accordion（手风琴）

Replace Collapse JS with native

<details>

<summary>

. The

name

attribute creates exclusive groups (replaces

data-bs-parent

). Add

.accordion-icon

SVG inside

<summary>

. Remove

.accordion-button

and

.accordion-collapse

. New modifiers:

.accordion-sm

for compact padding and type,

.accordion-gap

to space items as separate rounded cards.

html

<!-- v5 -->
<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>

<!-- v6 -->
<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>

用原生

<details>

<summary>

替换 Collapse JS。

name

属性用于创建互斥组（替代

data-bs-parent

）。在

<summary>

内添加

.accordion-icon

SVG。移除

.accordion-button

和

.accordion-collapse

。新增修饰类：

.accordion-sm

用于紧凑内边距和字体，

.accordion-gap

用于将条目间距设为独立的圆角卡片样式。

html

<!-- v5 -->
<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>

<!-- v6 -->
<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>

Cards

Cards（卡片）

Review card markup and any custom card CSS. v6 changes card borders, layout, and several helper classes.

```
.card
```
owns the background, outer border, radius, shadow, and height. Headers and footers draw only their divider border.
```
.card-body
```
is optional. It is now a flex column that removes direct-child block margins and uses
```
--card-body-gap
```
for spacing. Add
```
.flex-row
```
for a horizontal body.
Keep
```
.list-group-flush
```
on list groups inside cards. Do not add
```
.card-list
```
; that class is not available.
```
.card-title
```
and
```
.card-text
```
no longer add styles. Keep them only as project hooks.
```
.card-subtitle
```
still reduces the gap above the subtitle.
```
.card-link
```
is removed. Use normal links and flex or gap utilities when you need a link row.
Use
```
.card-row
```
for horizontal cards. Use
```
.card-subtle
```
or
```
.card-translucent
```
for the new visual variants.
Card groups now use a container query. Add
```
.contains-inline
```
to a parent or the cards remain stacked.

检查卡片标记和任何自定义卡片 CSS。v6 更改了卡片的边框、布局和几个辅助类。

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

Menu (was Dropdown)

Menu（原 Dropdown）

Remove

.dropdown

wrapper and

.dropdown-toggle

. Flatten

<ul><li><a>

<div><a>

. Toggle and

.menu

are siblings.

html

<!-- v5 -->
<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>

<!-- v6 -->
<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>

移除

.dropdown

包装器和

.dropdown-toggle

。将

<ul><li><a>

扁平化为

<div><a>

。触发器和

.menu

是兄弟元素。

html

<!-- v5 -->
<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>

<!-- v6 -->
<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>

Close button

关闭按钮

The markup does not change —

.btn-close

stays an empty element. Do not add a child SVG (that double-renders the icon). What changed is internal: v6 draws the icon with a CSS

mask

(

--btn-close-icon

) over

background-color: currentcolor

, so the button now inherits the current text

color

instead of a fixed image.

html

<!-- v5 and v6 — identical markup -->
<button type="button" class="btn-close" aria-label="Close"></button>

Because the icon is

currentcolor

, the v5

.btn-close-white

variant is removed — to get a light close button, set the text color (e.g. place it in a dark

.theme-*

context or add a

.fg-*

color

utility) instead.

标记没有变化——

.btn-close

仍然是空元素。不要添加子 SVG（会导致图标重复渲染）。变化在于内部实现：v6 使用 CSS

mask

（

--btn-close-icon

）叠加

background-color: currentcolor

绘制图标，因此按钮现在继承当前文本的

color

，而非使用固定图片。

html

<!-- v5 and v6 — identical markup -->
<button type="button" class="btn-close" aria-label="Close"></button>

由于图标使用

currentcolor

，v5 的

.btn-close-white

变体已被移除——要获得浅色关闭按钮，请设置文本颜色（例如将其放在深色

.theme-*

上下文中，或添加

.fg-*

color

工具类）。

Checkbox

Checkbox（复选框）

Apply

.check

directly on the

<input>

. No wrapper and no inline SVG — the mark is a CSS

mask

::before

. Radios (

.radio

) follow the same pattern. Switches keep a

.switch

wrapper around the input.

html

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

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

Radio and switch equivalents:

html

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

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

直接在

<input>

上应用

.check

。无需包装器，也无需内联 SVG——对勾是

::before

上的 CSS

mask

。单选框（

.radio

）遵循相同模式。开关（Switch）在输入框外保留

.switch

包装器。

html

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

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

Radio 和 switch 等效示例：

html

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

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

Toggle buttons

切换按钮

Input is now nested inside the label.

.btn-check

goes on the label. No

id

for

needed.

html

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

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

输入框现在嵌套在标签内部。

.btn-check

应用在标签上。无需

id

for

。

html

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

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

Range

Range（滑块）

.form-range

is now a wrapper and a JavaScript hook. Move the class from the input to a wrapper and add

.form-range-input

to the input.

html

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

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

.form-range

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

.form-range-input

。

html

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

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

Breadcrumbs

Breadcrumbs（面包屑）

Add

.breadcrumb-link

<a>

elements. Add empty

.breadcrumb-divider

separators between items (replaces

::before

pseudo-elements). An empty divider renders a default chevron via a CSS mask. The default bottom margin is gone (v5 used

$spacer

html

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

<!-- v6 -->
<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>

在

<a>

元素上添加

.breadcrumb-link

。在条目之间添加空的

.breadcrumb-divider

分隔符（替代

::before

伪元素）。空分隔符通过 CSS mask 渲染默认的 Chevron 图标。默认的下边距已移除（v5 使用

$spacer

）。

html

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

<!-- v6 -->
<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>

Step 4: JavaScript

步骤4：JavaScript

ESM-only

仅支持 ESM

All dist files are now ES modules. No more UMD bundles or

window.bootstrap

global.

html

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

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

Replace global namespace access with imports:

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

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

const tooltip = Tooltip.getOrCreateInstance(el)

Data API initialization still runs automatically after you add

type="module"

. Apply the component and data attribute renames in this skill. Bundler imports (

import { X } from 'bootstrap'

) work as before.

The bundled build includes Floating UI and Vanilla Calendar Pro. The standalone build requires installed peers or a browser import map.

所有发布文件现在都是 ES 模块。不再提供 UMD 包或

window.bootstrap

全局对象。

html

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

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

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

// v5 — 全局命名空间
const tooltip = bootstrap.Tooltip.getOrCreateInstance(el)

// v6 — 显式导入
import { Tooltip } from './bootstrap.bundle.min.js'

const tooltip = Tooltip.getOrCreateInstance(el)

添加

type="module"

后，数据 API 初始化仍然会自动运行。请应用本技能中提到的组件和数据属性重命名。打包器导入（

import { X } from 'bootstrap'

）的工作方式与之前相同。

捆绑构建版本包含 Floating UI 和 Vanilla Calendar Pro。独立构建版本需要安装 peer 依赖或浏览器 import map。

Renamed JS exports

重命名的 JS 导出

v5	v6
`Modal`	`Dialog`
`Offcanvas`	`Drawer`
`Dropdown`	`Menu`

v5	v6
`Modal`	`Dialog`
`Offcanvas`	`Drawer`
`Dropdown`	`Menu`

Popper -> Floating UI

Replace

@popperjs/core

with

@floating-ui/dom

. Rename the

popperConfig

option to

floatingConfig

on Tooltip, Popover, and Menu.

将

@popperjs/core

替换为

@floating-ui/dom

。将 Tooltip、Popover 和 Menu 上的

popperConfig

选项重命名为

floatingConfig

。

Lifecycle methods return a promise

生命周期方法返回 Promise

show()

hide()

toggle()

, and

close()

now return a promise that resolves when the transition ends. You can

await

them instead of listening for

shown.bs.*

hidden.bs.*

. The events still fire.

Hover and focus tooltips stay open while the pointer or focus is on the tip itself (WCAG 1.4.13). Press Escape or leave both the trigger and the tip to hide it.

Popup datepickers close on outside interaction, on <kbd>Escape</kbd>, or when focus leaves the input and calendar.

show()

、

hide()

、

toggle()

和

close()

现在返回一个 Promise，在过渡结束时 resolve。你可以

await

它们，而无需监听

shown.bs.*

hidden.bs.*

事件。事件仍然会触发。

悬停和聚焦的 Tooltip 在指针或焦点位于提示本身时会保持打开状态（符合 WCAG 1.4.13）。按 Escape 或同时离开触发器和提示即可隐藏。

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

TypeScript declarations

TypeScript 声明

Bootstrap’s source is now TypeScript. The package includes type declarations, so remove

@types/bootstrap

. Deep

.js

imports resolve to compiled

js/dist

files.

Bootstrap 的源码现在是 TypeScript 编写的。包中包含类型声明，因此请移除

@types/bootstrap

。深层

.js

导入会解析到编译后的

js/dist

文件。

Removed

已移除

jQuery support

bootstrap.esm.js

bootstrap.esm.min.js

— use

bootstrap.js

```
js/index.umd.js
```

jQuery 支持

bootstrap.esm.js

bootstrap.esm.min.js

—— 使用

bootstrap.js

```
js/index.umd.js
```

Validation 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

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

// v6
document.querySelectorAll('form[data-bs-validate]')
// 完全移除 was-validated 相关代码

Step 5: Sass

步骤5：Sass

Renamed files

重命名的文件

v5	v6
`_variables.scss`	`_config.scss`
`_variables-dark.scss`	Removed (merged into `_theme.scss` )
`_maps.scss`	Removed
`_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`	Removed
`vendor/_rfs.scss`	Removed

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`	已移除

Renamed variables and functions

重命名的变量与函数

v5	v6
`$grid-breakpoints`	`$breakpoints`
`$border-radius` , `$border-radius-sm/lg/xl/xxl` , `$border-radius-pill`	Removed — see the radius scale below
`$text-muted`	Use secondary color
`$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`	Removed — icon uses `currentcolor`
`add()` / `subtract()`	`calc()`
`breakpoint-infix()`	`breakpoint-prefix()` (returns `"md\:"` not `"-md"` )
`$infix` (in loop mixins)	`$prefix`
`$prefix` (CSS var prefix)	Removed — use PostCSS instead

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`
`add()` / `subtract()`	`calc()`
`breakpoint-infix()`	`breakpoint-prefix()` （返回 `"md\:"` 而非 `"-md"` ）
循环 mixin 中的 `$infix`	`$prefix`
（CSS 变量前缀） `$prefix`	已移除——改用 PostCSS

Border radius scale

圆角刻度

The

$border-radius-*

variables are gone. v6 uses a single base

$radius: .5rem

and a

$radii

map (keys

–

, e.g.

5: $radius

9: $radius * 2

), exposed as

--radius-0

–

--radius-9

tokens (plus

--radius-pill

). The

.rounded-*

utilities now span

–

and map to different values than v5, so shift class numbers up to keep the same roundness (e.g.

.rounded-1

→

.rounded-3

.rounded-3

→

.rounded-5

). Override the base or the map entries rather than the old per-size variables:

scss

// $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";

$border-radius-*

变量已移除。v6 使用单一的基础值

$radius: .5rem

和一个

$radii

映射（键为

–

，例如

5: $radius

，

9: $radius * 2

），对外暴露为

--radius-0

–

--radius-9

令牌（以及

--radius-pill

）。

.rounded-*

工具类现在覆盖

–

的范围，且对应的值与 v5 不同，因此请将类的数字调大以保持相同的圆角程度（例如

.rounded-1

→

.rounded-3

，

.rounded-3

→

.rounded-5

）。请覆盖基础值或映射条目，而非旧的按尺寸变量：

scss

// $radius 定义在 _config.scss 中，因此请在加载 Bootstrap 前配置该模块
@use "bootstrap/scss/config" with (
  $radius: .375rem // 按比例缩放整个映射
);
@use "bootstrap/scss/bootstrap";

Removed (no replacement)

已移除（无替代方案）

```
$nested-kbd-font-weight
```
```
$enable-dark-mode
```
— dark mode is always compiled
```
$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
```
All
```
*-focus-box-shadow
```
variables — use
```
focus-ring()
```
mixin with
```
--focus-ring-*
```
CSS custom properties
RFS mixins — use
```
clamp()
```
for responsive sizing
```
create-css-vars()
```
mixin
Caret mixins (
```
caret()
```
,
```
caret-down()
```
,
```
caret-up()
```
,
```
caret-end()
```
,
```
caret-start()
```
) — add an icon to the toggle markup instead
```
muted
```
,
```
black-50
```
,
```
white-50
```
from text color utilities map

```
$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()
```
mixin 配合
```
--focus-ring-*
```
CSS 自定义属性
RFS mixins——使用
```
clamp()
```
实现响应式尺寸
```
create-css-vars()
```
mixin
插入符号 mixin（
```
caret()
```
、
```
caret-down()
```
、
```
caret-up()
```
、
```
caret-end()
```
、
```
caret-start()
```
）——改为在触发器标记中添加图标
文本颜色工具映射中的
```
muted
```
、
```
black-50
```
、
```
white-50
```

Utility API

工具类 API

Removed

css-var

css-variable-name

, and

local-vars

options. Use

property

map and

variables

instead.

已移除

css-var

、

css-variable-name

和

local-vars

选项。改用

property

映射和

variables

。

Theme maps merge

主题映射合并

$theme-colors

$theme-bgs

$theme-fgs

$theme-borders

$badge-variants

, and other global maps use

defaults()

. Pass only the keys you want to change through

@use ... with ()

. Set a key to

null

to drop it. Nested theme-color maps merge one level deep — pass the whole sub-map to change one role.

Root tokens emit on

:root, :host

. Repeat

:root

overrides on

:host

if you use shadow DOM.

$theme-colors

、

$theme-bgs

、

$theme-fgs

、

$theme-borders

、

$badge-variants

和其他全局映射使用

defaults()

。只需通过

@use ... with ()

传入你想要修改的键。将键设为

null

即可删除它。嵌套的主题颜色映射仅合并一层——要修改某个角色，请传入整个子映射。

根令牌会在

:root, :host

上输出。如果你使用 Shadow DOM，请在

:host

上重复

:root

的覆盖。

Rebuilt behavior & new components

重构的行为与新增组件

Beyond the renames above, several things changed how a v5 project behaves or what's available. Check the docs for full markup/options.

除了上述重命名之外，还有一些功能改变了 v5 项目的行为方式，或新增了可用功能。完整的标记/选项请参阅文档。

Carousel — rebuilt on CSS scroll-snap

Carousel（轮播）——基于 CSS scroll-snap 重构

The markup (

.carousel

→

.carousel-inner

→

.carousel-item

) and the JS API (

next

prev

to

cycle

pause

slide

slid

events) are preserved, but several things changed:

ride
→
autoplay
(boolean, opt-in).
```
data-bs-ride="carousel"
```
becomes
```
data-bs-autoplay="true"
```
;
```
{ ride: 'carousel' }
```
becomes
```
{ autoplay: true }
```
. Default is
```
autoplay: false
```
, so a v5 carousel that auto-advanced now sits still until you opt in. Interacting with an autoplaying carousel now permanently stops it (WCAG 2.2.2).
wrap
→
ends
.
```
wrap: true
```
→
```
ends: "wrap"
```
(or the new default
```
"loop"
```
);
```
wrap: false
```
→
```
ends: "stop"
```
. Set via
```
data-bs-ends
```
. The
```
touch
```
option is removed (native scroll handles it).

Removed classes:

.carousel-control-prev/next

(compose a

.btn-icon

data-bs-slide

.carousel-icon-prev/next

.carousel-caption

(use your own markup),

.carousel-dark

(use

data-bs-theme="dark"

.carousel-stacked

(now the default), and the transitional

.carousel-item-start/end/next/prev

. Overlaid controls now require

.carousel-overlay

. Control-icon classes renamed

.carousel-control-prev-icon

→

.carousel-icon-prev

(and

-next

标记（

.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 — rebuilt on IntersectionObserver

ScrollSpy（滚动监听）——基于 IntersectionObserver 重构

The

data-bs-spy="scroll"

markup and the

activate.bs.scrollspy

event are unchanged, but detection is now driven by an activation line (no scroll-position polling), and the options changed:

Removed the deprecated
offset
and
method
options (deprecated since v5.1.3) — no longer parsed.
Added
topMargin
(default
```
12%
```
) — positions the activation line as a
```
%
```
or
```
px
```
value from the top of the scroll root (e.g.
```
96px
```
to sit below a sticky navbar). This is the everyday knob; use it instead of
```
rootMargin
```
.
rootMargin
is now an advanced override (default
```
null
```
, was
```
'0px 0px -25%'
```
); when set it takes precedence over
```
topMargin
```
and is passed straight to the observer.
threshold
default changed from
```
[0.1, 0.5, 1]
```
to
```
[0]
```
.
With smoothScroll
, clicking a link now restores the URL hash (
```
history.replaceState
```
) and moves focus to the target once the scroll settles (better keyboard/AT nav).
Target
```
id
```
s are resolved with
```
getElementById
```
, so ids with dots, colons, slashes, or percent-encoding work without manual escaping.

data-bs-spy="scroll"

标记和

activate.bs.scrollspy

事件保持不变，但检测现在由激活线驱动（不再轮询滚动位置），且选项发生了变化：

已移除弃用的
offset
和
method
选项（自 v5.1.3 起弃用）——不再解析。
新增
topMargin
（默认
```
12%
```
）——将激活线定位在滚动根元素顶部的百分比或像素值位置（例如
```
96px
```
可让激活线位于粘性导航栏下方）。这是常用的调节参数；请用它替代
```
rootMargin
```
。
rootMargin
现在是高级覆盖选项（默认
```
null
```
，之前为
```
'0px 0px -25%'
```
）；设置后它会优先于
```
topMargin
```
，并直接传递给观察者。
threshold
默认值从
```
[0.1, 0.5, 1]
```
改为
```
[0]
```
。
启用 smoothScroll
后，点击链接现在会恢复 URL 哈希（
```
history.replaceState
```
），并在滚动结束后将焦点移到目标元素（更好的键盘/辅助技术导航体验）。
目标
```
id
```
通过
```
getElementById
```
解析，因此包含点、冒号、斜杠或百分号编码的 id 无需手动转义即可正常工作。

Collapse — simplified state and transitions

Collapse（折叠）——简化的状态与过渡

Remove selectors and tests that depend on
```
.collapsing
```
. Collapse now toggles
```
.show
```
and uses native size interpolation.
Replace trigger
```
.collapsed
```
selectors with
```
[aria-expanded="false"]
```
.
Remove the
```
toggle
```
constructor option. Call
```
show()
```
or
```
hide()
```
when initialization must change state.

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

New components (didn't exist in v5)

新增组件（v5 中不存在）

Component	Trigger / hook	Purpose
Combobox	`data-bs-toggle="combobox"`	Filterable/autocomplete select built on Menu
Chip / Chip input	`.chip` , `.chip-input` ( `data-bs-chips` )	Tags / tokens + interactive entry
Datepicker	`data-bs-toggle="datepicker"`	Date picker (peer dep `vanilla-calendar-pro` )
Range	`.form-range` (+ `data-bs-bubble` , ticks)	Enhanced range slider with a value bubble
Strength	`data-bs-strength`	Password-strength meter
OTP input	`data-bs-otp`	One-time-code input
Nav overflow	`.nav-overflow` wrapper around a `.nav`	Collapses overflowing nav items into a menu
Toggler	`data-bs-toggle="toggler"`	Generic class/attribute toggler
Submenu	`.submenu` (within Menu)	Nested menus ( `submenuTrigger` , `submenuDelay` )
Stepper	`.stepper`	Multi-step workflow (CSS-only)
Avatar	`.avatar`	Avatars with sizes, status, `.avatar-stack` (CSS-only)
Form adorn	`.form-adorn`	Icon/text decoration on inputs (CSS-only)
Prose	`.prose` / `.not-prose`	Rich-typography scoping (CSS-only)

组件	触发器/钩子	用途
Combobox	`data-bs-toggle="combobox"`	基于 Menu 构建的可筛选/自动完成选择器
Chip / Chip input	`.chip` 、 `.chip-input` （ `data-bs-chips` ）	标签/令牌 + 交互式输入
Datepicker	`data-bs-toggle="datepicker"`	日期选择器（peer 依赖 `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	（Menu 内的） `.submenu`	嵌套菜单（ `submenuTrigger` 、 `submenuDelay` ）
Stepper	`.stepper`	多步骤工作流（仅 CSS）
Avatar	`.avatar`	带尺寸、状态的头像，支持 `.avatar-stack` （仅 CSS）
Form adorn	`.form-adorn`	输入框上的图标/文本装饰（仅 CSS）
Prose	`.prose` / `.not-prose`	富文本排版作用域（仅 CSS）

Removed / changed internals

已移除/变更的内部实现

util/backdrop.js
,
util/focustrap.js
, and
util/scrollbar.js
removed. Dialog and Drawer use the native
```
<dialog>
```
element, which provides the backdrop (
```
::backdrop
```
), the focus trap, and an inert top layer; the body scroll-lock is now CSS (
```
:root.dialog-open
```
). If you imported
```
bootstrap/js/src/util/backdrop
```
,
```
.../focustrap
```
, or
```
.../scrollbar
```
directly, they're gone.
CSS
@layer
. Component styles are wrapped in cascade layers (
```
colors, theme, config, root, reboot, layout, content, forms, components, custom, helpers, utilities
```
). Author CSS outside any layer now wins over Bootstrap regardless of source order — if your v5 overrides relied on specificity or load order, re-check them.

--bs-*-rgb
variables removed. The

$*-rgb

Sass vars and

--bs-*-rgb

custom properties are gone. Replace

rgba(var(--bs-primary-rgb), .5)

with

color-mix(in oklab, var(--bs-primary), transparent 50%)

(or use the color directly).

util/backdrop.js
、
util/focustrap.js
和
util/scrollbar.js
已移除。 Dialog 和 Drawer 使用原生
```
<dialog>
```
元素，它提供了背景（
```
::backdrop
```
）、焦点陷阱和惰性顶层；body 滚动锁定现在由 CSS 实现（
```
:root.dialog-open
```
）。如果你直接导入了
```
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%)

（或直接使用颜色）。

Step 6: Verify

步骤6：验证

Build the project and fix any compilation errors.
Search for remaining v5 patterns:
- ```
modal
```
  classes/attributes (should be
```
dialog
```
  )
- ```
offcanvas
```
  (should be
```
drawer
```
  )
- ```
dropdown
```
  (should be
```
menu
```
  )
- ```
d-md-
```
  ,
```
d-lg-
```
  ,
```
col-md-
```
  , etc. (should use
```
md:
```
  prefix syntax)
- ```
btn-primary
```
  ,
```
btn-outline-
```
  (should use
```
.btn-solid .theme-*
```
  )
- ```
.text-primary
```
  ,
```
.text-danger
```
  (should be
```
.fg-*
```
  )
- ```
@import
```
  in Sass (should be
```
@use
```
  )
- ```
form-select
```
  (should be
```
form-control
```
  )
- ```
was-validated
```
  ,
```
needs-validation
```
  (should be
```
data-bs-validate
```
  )
- ```
popperConfig
```
  (should be
```
floatingConfig
```
  )
- ```
form-check
```
  (should be
```
check
```
  ,
```
radio
```
  , or
```
switch
```
  )
- ```
var(--bs-*-rgb)
```
  /
```
rgba(var(--bs-…-rgb)
```
  (removed — use
```
color-mix()
```
  )
- ```
$border-radius
```
  Sass vars (removed — use
```
$radius
```
  /
```
$radii
```
  /
```
--radius-*
```
  )
- child
```
<svg>
```
  inside
```
.btn-close
```
  (should be empty — icon is a CSS mask)
- ```
.btn-close-white
```
  (removed — set text
```
color
```
  instead)
- ```
<div class="drawer">
```
  (must be a native
```
<dialog class="drawer">
```
  )
- ```
data-bs-ride
```
  (renamed to
```
data-bs-autoplay
```
  );
```
wrap:
```
  carousel option (now
```
ends:
```
  )
- ```
.carousel-control-prev/next
```
  ,
```
.carousel-caption
```
  ,
```
.carousel-dark
```
  ,
```
.carousel-stacked
```
  (all removed)
- ```
.fs-1
```
  –
```
.fs-6
```
  (should be
```
.fs-4xl
```
  …
```
.fs-md
```
  )
- ```
.link-offset-*
```
  /
```
.link-underline-*
```
  (now
```
.underline-offset-*
```
  /
```
.underline-*
```
  )
- ScrollSpy
```
offset
```
  /
```
method
```
  options (removed — use
```
topMargin
```
  )
- inline SVG inside
```
.check
```
  (icon is a CSS mask on the input)
- ```
$theme-colors
```
  full-map replacements (v6 merges via
```
defaults()
```
  )
- ```
.collapsing
```
  ,
```
.collapsed
```
  trigger selectors, and the Collapse
```
toggle
```
  option
- responsive stacks, CSS Grid, navbars, list groups, card groups, and stacked tables without a query container
Test in browser — v6 requires support for
```
oklch()
```
and
```
color-mix()
```
.

构建项目并修复所有编译错误。
搜索剩余的 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 mask）
- ```
.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 mask）
- ```
$theme-colors
```
  全映射替换（v6 通过
```
defaults()
```
  合并）
- ```
.collapsing
```
  、
```
.collapsed
```
  触发器选择器，以及 Collapse 的
```
toggle
```
  选项
- 没有查询容器的响应式堆叠、CSS Grid、导航栏、列表组、卡片组和堆叠表格
在浏览器中测试——v6 需要支持
```
oklch()
```
和
```
color-mix()
```
。