bootstrap-v4-v6-migration

Bootstrap v4 到 v6 迁移

没有从 v4 直接迁移到 v6 的路径。请分两阶段迁移——先从 v4 迁移到 v5（使用本技能），再从 v5 迁移到 v6（使用 bootstrap-v5-v6-migration 技能）。跳过中间阶段行不通，因为许多 v4 名称在 v5 中改名后，在 v6 中又再次改名：.text-primary 只有经过 v5 后才会变成 .fg-primary，而 .badge-primary 则会先变成 .badge.bg-primary，再变为 .badge.theme-primary。

工作流

按顺序完成每个步骤。每完成一步，都要搜索代码库中是否还存在 v4 模式，再继续下一步。

• 步骤 1：规划两阶段迁移
• 步骤 2：v4 到 v5——依赖项、构建和 Sass
• 步骤 3：v4 到 v5——JavaScript
• 步骤 4：v4 到 v5——类和属性
• 步骤 5：v5 到 v6——转交给 v6 迁移技能
• 步骤 6：验证

---

步骤 1：规划两阶段迁移

1. 先让项目迁移到 Bootstrap 5 并正常运行——构建通过、页面正常渲染、测试通过——然后再处理 v6。将 v5 阶段作为单独的提交（或 PR）合并，可以在出现问题时区分两轮改名。
2. 先盘点项目中的内容。v4 中最耗时的功能包括自定义表单、.input-group-append / .input-group-prepend、巨幕、.media 对象、.card-deck / .card-columns，以及调用 Bootstrap 插件的任何 jQuery 代码。
3. 单独决定如何处理 jQuery。Bootstrap 5 移除了对它的依赖，但你的应用可能还会在其他地方使用它；移除 Bootstrap 对 jQuery 的依赖并不意味着必须移除 jQuery 本身。
4. 留意最低浏览器版本要求。Bootstrap 5 不再支持 IE。Bootstrap 6 要求 macOS 和 iOS 上的 Chrome 和 Edge 130、Firefox 132 以及 Safari 18。

---

步骤 2：v4 到 v5——依赖项、构建和 Sass

1. 更新依赖项，并移除 jQuery / Popper v1 组合：

   npm i --save bootstrap@5 @popperjs/core
   npm uninstall popper.js
   

   popper.js（v1）由 @popperjs/core（v2）取代。Bootstrap 5 的 bundle 包含 Popper；独立的 bootstrap.js 则不包含。

2. 将 Sass 编译器切换为 Dart Sass（npm i --save-dev sass）。不支持 Node Sass / LibSass。暂时继续使用 @import——v5 仍然使用它；迁移到 @use 会在 v6 阶段进行。

3. Sass 映射不再自动合并。在 v4 中，只需向 $theme-colors 添加一个键即可；在 v5 中，你必须定义完整的映射，包括要保留的键。

4. 更新已改名的函数和 mixin：

   v4	v5
   color-yiq()	color-contrast()
   theme-color()、gray()	已移除——直接引用 $theme-colors / $grays
   theme-color-level()	tint-color() / shade-color()
   lighten() / darken()	tint-color() / shade-color()
   media-breakpoint-down(md)	media-breakpoint-down(lg)——参数是断点本身，而不是下一个较低断点
   media-breakpoint-between(sm, md)	media-breakpoint-between(sm, lg)——上限也有相同变化

   断点参数的变化不会触发错误：媒体查询只会应用到相差一个断点的位置。请检查每一次调用。

5. v5 中，打印样式、$enable-* 标志以及工具 API 都发生了变化。如果你使用 v4 mixin 生成了自定义工具类，请通过 v5 的 $utilities 映射重写它们。

---

第 3 步：v4 到 v5 — JavaScript

1. 为每个数据属性添加 bs 命名空间。这是一项机械性但影响广泛的更改：

   v4	v5
   data-toggle	data-bs-toggle
   data-target	data-bs-target
   data-dismiss	data-bs-dismiss
   data-parent	data-bs-parent
   data-ride	data-bs-ride
   data-slide, data-slide-to	data-bs-slide, data-bs-slide-to
   data-spy	data-bs-spy
   data-backdrop, data-keyboard	data-bs-backdrop, data-bs-keyboard
   data-content, data-placement, data-trigger	data-bs-content, data-bs-placement, data-bs-trigger

   作为属性传入的任何选项也遵循相同规则：data-<option> 变为 data-bs-<option>。

2. 将 jQuery 插件调用替换为构造函数或静态获取器：

   // v4
   $('#myModal').modal('show')
   $('#myTooltip').tooltip()
   
   // v5
   const modal = new bootstrap.Modal(document.querySelector('#myModal'))
   modal.show()
   
   bootstrap.Tooltip.getOrCreateInstance(document.querySelector('#myTooltip'))
   

3. 将 jQuery 事件处理程序替换为原生监听器。Bootstrap 5 会派发原生 CustomEvent，因此 $(el).on('shown.bs.modal', …) 将不再触发：

   // v5
   document.querySelector('#myModal').addEventListener('shown.bs.modal', event => {
     // event.relatedTarget replaces event.relatedTarget from the jQuery event
   })
   

4. 其他较小的 API 重命名：

   • _getInstance() → getInstance()，并优先使用新的 getOrCreateInstance()。
   • 清理器选项 whiteList → allowList。
   • Tooltip 和 Popover 的 title / content 仍接受函数，但 this 不再是 jQuery 元素。

5. 如果你依赖 jQuery 的 noConflict 或 $.fn.button('toggle') 这类调用，请改用类 API 重写——已经没有可供填补的 jQuery 接口。

---

第 4 步：v4 到 v5 — 类和属性

方向性工具类改为逻辑方向（支持 RTL）

v4	v5
.ml-*, .mr-*	.ms-*, .me-*
.pl-*, .pr-*	.ps-*, .pe-*
.float-left, .float-right	.float-start, .float-end
.text-left, .text-right	.text-start, .text-end
.border-left, .border-right	.border-start, .border-end
.rounded-left, .rounded-right	.rounded-start, .rounded-end
.dropleft, .dropright	.dropstart, .dropend

响应式变体也遵循相同的重命名规则（.ml-md-3 → .ms-md-3）。

排版和辅助类

v4	v5
.font-weight-bold, -normal, -light, -bolder, -lighter	.fw-bold, .fw-normal, .fw-light, .fw-bolder, .fw-lighter
.font-italic	.fst-italic
.text-monospace	.font-monospace
.sr-only, .sr-only-focusable	.visually-hidden, .visually-hidden-focusable
.embed-responsive, .embed-responsive-16by9	.ratio, .ratio-16x9
.text-justify, .text-hide, .pre-scrollable	已移除
.rounded-sm, .rounded-lg	.rounded-1, .rounded-3

表单

这是 v4 到 v5 改写幅度最大的一项：自定义表单控件已合并到标准类中。

v4	v5
.custom-select	.form-select
.custom-range	.form-range
.custom-file, .form-control-file	.form-control（用于 <input type="file">）
.form-control-range	.form-range
.custom-control.custom-checkbox	.form-check
.custom-control.custom-radio	.form-check
.custom-control.custom-switch	.form-check.form-switch
.custom-control-input	.form-check-input
.custom-control-label	.form-check-label
.custom-control-inline	.form-check-inline
.form-group	间距工具类，例如 .mb-3
.form-row	.row 加间距工具类（.g-*）
.form-inline	网格或弹性布局工具类（.row .row-cols-lg-auto、.d-flex）
没有类的 <label>	<label class="form-label">

输入组不再需要包装元素：删除 .input-group-append 和 .input-group-prepend，并将 .input-group-text、按钮和控件作为 .input-group 的直接子元素。验证反馈也应移出已删除的包装元素。

已移除或重构的组件

v4	v5
.jumbotron	已移除——使用 .bg-*、.p-*、.rounded-* 组合实现
.media	已移除——使用 .d-flex 和间距／外边距工具类
.card-deck、.card-columns	已移除——使用网格，或使用 CSS 多列实现瀑布流
.close	.btn-close（移除 × 子元素；图标为背景图片）
.badge-primary 等	.badge 加 .bg-primary
.badge-pill	.rounded-pill
.btn-block	使用 .d-grid 容器（为堆叠按钮添加 .gap-*）
.thead-light、.thead-dark	在 <thead> 上使用 .table-light、.table-dark
.arrow（tooltip/popover）	.tooltip-arrow、.popover-arrow
.carousel-item-left、-right	.carousel-item-start、-end

徽章也失去了链接样式——<a class="badge"> 不再具有悬停／焦点状态。

网格、导航栏和导航

• .no-gutters → .g-0，现在可通过 .g-*、.gx-*、.gy-* 工具类控制间距。
• 新增了 xxl 断点（1400px）；现有 xl 类的含义保持不变。
• 现在必须在 .navbar 内添加容器（<nav class="navbar"><div class="container">…）。
• 对于标签页和胶囊式导航，.active 从 .nav-item 移至 .nav-link。.nav-item 可作为可选容器。
• .dropdown-menu 项可以是 <button> 或 <a>；新增了用于纯文本的 .dropdown-item-text。

---

步骤 5：从 v5 迁移到 v6——转交给 v6 迁移技能

项目在 Bootstrap 5 上成功构建并渲染后，切换到 bootstrap-v5-v6-migration 技能并按步骤操作。v4 模式仍存在时不要尝试重命名——其中的查找和替换步骤假定使用的是 v5 名称。

这一阶段涵盖的内容包括：

• 将 @import 改为 @use，并从 Sass 标量转向 CSS 令牌映射（v6 中的 defaults() 会再次合并主题映射）
• 从 Popper 迁移到 Floating UI，并为 Datepicker 使用 Vanilla Calendar Pro。捆绑构建包含这两个对等依赖；独立构建则将它们保留为外部依赖。
• 使用 md: 响应式前缀语法替代 -md- 插入形式
• 将 Modal 改为 Dialog、Offcanvas 改为 Drawer、Dropdown 改为 Menu。Dialog 和 Drawer 使用原生 <dialog> 元素。
• 将 .btn-primary 改为 .btn-solid .theme-primary，将 .text-* 改为 .fg-*
• 仅支持 ESM 的 JavaScript，不再提供 window.bootstrap 全局变量
• 用于响应式堆叠布局、CSS Grid、导航栏、列表组、卡片组和堆叠表格的容器查询上下文

开始前值得注意两个 v4 时代的细节：你在步骤 4 中生成的 .close → .btn-close 元素在 v6 中仍保留此名称（但必须为空，不能有子 SVG）；而你刚刚编写的 .form-check 标记则会再次重构为 v6 的 .check／.radio／.switch 结构。

步骤 6：验证

1. 构建项目，并在查看渲染结果之前修复编译错误。
2. 搜索遗留的 v4 模式：
   • data-toggle=, data-target=, data-dismiss=, data-ride=, data-slide, data-spy=（都应改为 data-bs-*）
   • 关闭按钮中的 class="close"、×（应改为 .btn-close）
   • badge-, badge-pill（应改为 .badge .bg-* / .rounded-pill）
   • custom-select, custom-control, custom-switch, custom-range, custom-file
   • form-group, form-row, form-inline, input-group-append, input-group-prepend
   • \bm[lr]-, \bp[lr]-, float-left, float-right, text-left, text-right, border-left, border-right
   • font-weight-, font-italic, text-monospace
   • no-gutters, sr-only, embed-responsive, jumbotron, media-body, card-deck, card-columns, btn-block, thead-light, thead-dark, pre-scrollable, text-justify
   • Bootstrap 插件名称（.modal(、.tooltip(、.collapse(）附近的 \$(、jQuery(
   • theme-color(, color-yiq(, theme-color-level(, media-breakpoint-down(
3. 逐一点击每个交互组件——数据属性重命名失败时不会显示任何错误，因此遗漏 data-toggle 会让按钮看起来无法使用，而不是报错。
4. 尤其仔细检查表单：自定义控件、输入组和验证反馈的结构都已更改。
5. 然后转到步骤 5，并在 v6 阶段重复这一套流程。