Skip to main content Skip to docs navigation

迁移到 v5

跟踪和回顾对 Bootstrap 源文件、文档和组件的更改，以帮助您从 v4 迁移到 v5。

依赖项

  • 放弃了 jQuery。
  • 从 Popper v1.x 升级到 Popper v2.x。
  • 鉴于 Libsass 已弃用，我们的 Sass 编译器从 Libsass 替换为 Dart Sass。
  • 从 Jekyll 迁移到 Hugo 以构建我们的文档

浏览器支持

  • 放弃 Internet Explorer 10 和 11
  • 放弃 Microsoft Edge < 16（旧版 Edge）
  • 放弃 Firefox < 60
  • 放弃 Safari < 12
  • 放弃 iOS Safari < 12
  • 放弃 Chrome < 60

文档更改

  • 重新设计的主页、文档布局和页脚。
  • 添加了新 Parcel 指南。
  • 添加了new Customize section, replacing v4 的主题页面, 包含有关 Sass、全局配置选项、配色方案、CSS 变量等的新细节。
  • 将所有表单文档重新组织到新表单部分，将内容分解为更集中的页面。
  • 同样，更新了布局部分，以更清晰地充实网格内容。
  • 将“Navs”组件页面重命名为“Navs & Tabs”。
  • 将“Checks”页面重命名为“Checks & radios”。
  • 重新设计了导航栏并添加了新的子导航，以便更轻松地浏览我们的网站和文档版本。
  • 为搜索功能加了新的键盘快捷键： Ctrl + /.

Sass

  • 我们放弃了默认的 Sass 映射merges ，以便更轻松地删除冗余值。 请记住，您现在必须在 Sass 映射中定义所有值，例如 $theme-colors。 查看如何处理 Sass 映射。

  • Breaking 将 color-yiq() 函数和相关变量重命名为 color-contrast()，因为它不再与 YIQ 颜色空间相关。 参见#30168。

    • $yiq-contrasted-threshold 重命名为 $min-contrast-ratio。
    • $yiq-text-dark 和 $yiq-text-light 分别重命名为 $color-contrast-dark 和 $color-contrast-light。

  • Breaking 媒体查询混合参数已更改为更合乎逻辑的方法。

    • media-breakpoint-down() 使用断点本身而不是下一个断点（例如，media-breakpoint-down(lg) 而不是 media-breakpoint- down(md) 目标视口小于 lg)。
    • 同样，media-breakpoint-between() 中的第二个参数也使用断点本身而不是下一个断点（例如，media-between(sm, lg) 而不是 media-breakpoint-between(sm, md) 以 sm 和 lg 之间的视口为目标。

  • Breaking 删除了打印样式和 $enable-print-styles 变量。 打印显示类仍然存在。 参见#28339。

  • Breaking 删除了 color()、theme-color() 和 gray() 函数以支持变量。 参见#29083。

  • Breaking 将 theme-color-level() 函数重命名为 color-level() 并且现在接受您想要的任何颜色，而不仅仅是 $theme-color 颜色。 参见#29083 注意： color-level() 后来在 v5.0.0-alpha3 中被删除。

  • Breaking 为简洁起见，将 $enable-prefers-reduced-motion-media-query 和 $enable-pointer-cursor-for-buttons 重命名为 $enable-reduced-motion 和 $enable-button-pointers。

  • Breaking 删除了 bg-gradient-variant() 混合。 使用 .bg-gradient 类而不是生成的 .bg-gradient-* 类向元素添加渐变。

  • Breaking 删除了以前不推荐使用的 mixin：

    • hover, hover-focus, plain-hover-focus, 和 hover-focus-active
    • float()
    • form-control-mixin()
    • nav-divider()
    • retina-img()
    • text-hide() (还删除了相关的实用程序类， .text-hide)
    • visibility()
    • form-control-focus()

  • Breaking 将 scale-color() 函数重命名为 shift-color() 以避免与 Sass 自己的颜色缩放函数发生冲突。

  • box-shadow mixins 现在允许 null 值并从多个参数中删除 none。 参见#30394。

  • border-radius() mixin 现在有一个默认值。

颜色系统

  • 与 color-level() 和 $theme-color-interval 一起使用的颜色系统已被删除，以支持新的颜色系统。 我们代码库中的所有 lighten() 和 darken() 函数都替换为 tint-color() 和 shade-color() 。 这些函数会将颜色与白色或黑色混合，而不是按固定量改变其亮度。 shift-color() 将根据权重参数是正还是负来 tint 或 shade 颜色。 查看#30622了解更多详情。

  • 为每种颜色添加了新的色调(tints)和阴影(shades)，为每种基色提供了九种不同的颜色，作为新的 Sass 变量。

  • 改善颜色对比度。 将颜色对比度从 3:1 提高到 4.5:1，并更新了蓝色、绿色、青色和粉红色，以确保 WCAG 2.1 AA 对比度。 还将我们的颜色对比色从 $gray-900 更改为 $black。

  • 为了支持我们的颜色系统，我们添加了新的自定义 tint-color() 和 shade-color() 函数来适当地混合我们的颜色。

网格更新

  • 新断点！为 1400px 及以上添加了新的 xxl 断点。 对所有其他断点没有更改。

  • 改进的沟槽(gutters)。沟槽现在以 rem 为单位设置，并且比 v4 更窄（1.5rem，或大约 24px，低于 30px ）。 这使我们的网格系统的沟槽与我们的间距实用程序对齐。

    • 添加了新的 gutter 类 (.g-*, .gx- * 和 .gy-*) 来控制水平/垂直沟槽、水平沟槽和垂直沟槽。
    • Breaking 将 .no-gutters 重命名为 .g-0 以匹配新的 gutter 实用程序。

  • 列不再应用 position: relative，因此您可能必须将 .position-relative 添加到某些元素以恢复该行为。

  • Breaking 删除了几个经常不用的 .order-* 类。 我们现在只提供 .order-1 到 .order-5 开箱即用。

  • Breaking 删除了 .media 组件，因为它可以使用实用程序轻松复制。 参见 #28265 和 以弹性实用程序页面为例。

  • Breaking bootstrap-grid.css 现在仅将 box-sizing:border-box 应用于列，而不是重置全局 box-sizing。 这样，我们的网格样式可以在更多的地方使用而不会受到干扰。

  • $enable-grid-classes 不再禁用容器类的生成。 参见#29146。

  • 将 make-col mixin 更新为默认为相等的列，但没有指定大小。

Content, Reboot, etc

  • RFS 现在默认启用。 使用 font-size() 混合的标题将 自动调整它们的 font-size 以随视口缩放。 此功能之前是在 v4 中选择加入的。

  • Breaking 彻底检查了我们的显示排版以替换我们的 $display-* 变量并使用 $display-font-sizes Sass 映射。 还删除了单个 $display-font-weight 的各个 $display-*-weight 变量并调整了 font-size。

  • 添加了两个新的 .display-* 标题大小，.display-5 和 .display-6。

  • 链接默认带有下划线（不仅仅是悬停），除非它们是特定组件的一部分。

  • 重新设计的表格以刷新其样式并使用 CSS 变量重新构建它们以更好地控制样式。

  • Breaking 嵌套表不再继承样式。

  • Breaking .thead-light 和 .thead-dark 被删除，取而代之的是可用于所有表格元素的 .table-* 变体类 （thead、tbody、tfoot、tr、th 和 td ）。

  • Breaking table-row-variant() mixin 被重命名为 table-variant() 并且只接受 2 个参数：$color（颜色名称） 和 $value（颜色代码）。 边框颜色和强调色是根据表格因子变量自动计算的。

  • 将表格单元格填充变量拆分为 -y 和 -x。

  • Breaking 删除了 .pre-scrollable 类。 见#29135

  • Breaking .text-* 实用程序不再向链接添加悬停和焦点状态。 .link-* 辅助类可以代替使用。 见#29267

  • Breaking Dropped .text-justify class. See #29793

  • Breaking <hr> 元素现在使用 height 而不是 border 以更好地支持 size 属性。 这也允许使用填充实用程序来创建更厚的分隔线（例如，<hr class="py-1">）。

  • 将 <ul> 和 <ol> 元素上的默认水平 padding-left 从浏览器默认 40px 重置为 2rem。

  • 添加了 $enable-smooth-scroll，它在全局范围内应用 scroll-behavior: smooth — 除了用户通过 prefers-reduced-motion 媒体查询。 见#31877

RTL

  • 水平方向特定的变量、实用程序和 mixin 都已重命名为使用类似于 flexbox 布局中的逻辑属性——例如，start 和 end 代替 left 和 正确。

Forms

  • 添加了新的浮动表单！我们已将浮动标签示例提升为完全支持的表单组件。 查看新的浮动标签页面。

  • Breaking 整合了原生和自定义表单元素。 复选框、单选、选择和其他在 v4 中具有原生和自定义类的输入已被整合。 现在几乎我们所有的表单元素都是完全自定义的，大多数不需要自定义 HTML。

    • .custom-check 现在是 .form-check。
    • .custom-check.custom-switch 现在是 .form-check.form-switch。
    • .custom-select 现在是 .form-select。
    • .custom-file 和 .form-file 已被顶部的自定义样式 .form-control 取代。
    • .custom-range 现在是 .form-range.
    • 删除了原生 .form-control-file 和 .form-control-range。

  • Breaking 删除了 .input-group-append 和 .input-group-prepend。 您现在可以添加按钮和 .input-group-text 作为输入组合框的直接子项。

  • 长期存在的输入组合框缺少边框半径和验证反馈错误最终解决通过添加额外的 .has-validation 类用于输入组合框验证。

  • Breaking 为我们的网格系统删除了特定于表单的布局类。使用我们的网格和实用程序而不是 .form-group、.form-row 或 .form-inline。

  • Breaking 表单标签现在需要 .form-label。

  • Breaking .form-text no longer sets display, allowing you to create inline or block help text as you wish just by changing the HTML element.

  • Validation icons are no longer applied to <select>s with multiple.

  • Rearranged source Sass files under scss/forms/, including input group styles.

Components

  • Unified padding values for alerts, breadcrumbs, cards, dropdowns, list groups, modals, popovers, and tooltips to be based on our $spacer variable. See #30564.

Accordion

Alerts

  • Alerts now have examples with icons.

  • Removed custom styles for <hr>s in each alert since they already use currentColor.

Badges

  • Breaking Dropped all .badge-* color classes for background utilities (e.g., use .bg-primary instead of .badge-primary).

  • Breaking Dropped .badge-pill—use the .rounded-pill utility instead.

  • Breaking Removed hover and focus styles for <a> and <button> elements.

  • Increased default padding for badges from .25em/.5em to .35em/.65em.

  • Simplified the default appearance of breadcrumbs by removing padding, background-color, and border-radius.

  • Added new CSS custom property --bs-breadcrumb-divider for easy customization without needing to recompile CSS.

Buttons

  • Breaking Toggle buttons, with checkboxes or radios, no longer require JavaScript and have new markup. We no longer require a wrapping element, add .btn-check to the <input>, and pair it with any .btn classes on the <label>. See #30650. The docs for this has moved from our Buttons page to the new Forms section.

  • Breaking Dropped .btn-block for utilities. Instead of using .btn-block on the .btn, wrap your buttons with .d-grid and a .gap-* utility to space them as needed. Switch to responsive classes for even more control over them. Read the docs for some examples.

  • Updated our button-variant() and button-outline-variant() mixins to support additional parameters.

  • Updated buttons to ensure increased contrast on hover and active states.

  • Disabled buttons now have pointer-events: none;.

Card

  • Breaking Dropped .card-deck in favor of our grid. Wrap your cards in column classes and add a parent .row-cols-* container to recreate card decks (but with more control over responsive alignment).

  • Breaking Dropped .card-columns in favor of Masonry. See #28922.

  • Breaking Replaced the .card based accordion with a new Accordion component.

  • Added new .carousel-dark variant for dark text, controls, and indicators (great for lighter backgrounds).

  • Replaced chevron icons for carousel controls with new SVGs from Bootstrap Icons.

Close button

  • Breaking Renamed .close to .btn-close for a less generic name.

  • Close buttons now use a background-image (embedded SVG) instead of a &times; in the HTML, allowing for easier customization without the need to touch your markup.

  • Added new .btn-close-white variant that uses filter: invert(1) to enable higher contrast dismiss icons against darker backgrounds.

Collapse

  • Removed scroll anchoring for accordions.

  • Added new .dropdown-menu-dark variant and associated variables for on-demand dark dropdowns.

  • Added new variable for $dropdown-padding-x.

  • Darkened the dropdown divider for improved contrast.

  • Breaking All the events for the dropdown are now triggered on the dropdown toggle button and then bubbled up to the parent element.

  • Dropdown menus now have a data-bs-popper="static" attribute set when the positioning of the dropdown is static and data-bs-popper="none" when dropdown is in the navbar. This is added by our JavaScript and helps us use custom position styles without interfering with Popper’s positioning.

  • Breaking Dropped flip option for dropdown plugin in favor of native Popper configuration. You can now disable the flipping behavior by passing an empty array for fallbackPlacements option in flip modifier.

  • Dropdown menus can now be clickable with a new autoClose option to handle the auto close behavior. You can use this option to accept the click inside or outside the dropdown menu to make it interactive.

  • Dropdowns now support .dropdown-items wrapped in <li>s.

Jumbotron

List group

  • Added new null variables for font-size, font-weight, color, and :hover color to the .nav-link class.
  • Breaking Navbars now require a container within (to drastically simplify spacing requirements and CSS required).

Offcanvas

Pagination

  • Pagination links now have customizable margin-left that are dynamically rounded on all corners when separated from one another.

  • Added transitions to pagination links.

Popovers

  • Breaking Renamed .arrow to .popover-arrow in our default popover template.

  • Renamed whiteList option to allowList.

Spinners

  • Spinners now honor prefers-reduced-motion: reduce by slowing down animations. See #31882.

  • Improved spinner vertical alignment.

Toasts

  • Toasts can now be positioned in a .toast-container with the help of positioning utilities.

  • Changed default toast duration to 5 seconds.

  • Removed overflow: hidden from toasts and replaced with proper border-radiuss with calc() functions.

Tooltips

  • Breaking Renamed .arrow to .tooltip-arrow in our default tooltip template.

  • Breaking The default value for the fallbackPlacements is changed to ['top', 'right', 'bottom', 'left'] for better placement of popper elements.

  • Breaking Renamed whiteList option to allowList.

Utilities

  • Breaking Renamed several utilities to use logical property names instead of directional names with the addition of RTL support:

    • Renamed .left-* and .right-* to .start-* and .end-*.
    • Renamed .float-left and .float-right to .float-start and .float-end.
    • Renamed .border-left and .border-right to .border-start and .border-end.
    • Renamed .rounded-left and .rounded-right to .rounded-start and .rounded-end.
    • Renamed .ml-* and .mr-* to .ms-* and .me-*.
    • Renamed .pl-* and .pr-* to .ps-* and .pe-*.
    • Renamed .text-left and .text-right to .text-start and .text-end.

  • Breaking Disabled negative margins by default.

  • Added new .bg-body class for quickly setting the <body>’s background to additional elements.

  • Added new position utilities for top, right, bottom, and left. Values include 0, 50%, and 100% for each property.

  • Added new .translate-middle-x & .translate-middle-y utilities to horizontally or vertically center absolute/fixed positioned elements.

  • Added new border-width utilities.

  • Breaking Renamed .text-monospace to .font-monospace.

  • Breaking Removed .text-hide as it’s an antiquated method for hiding text that shouldn’t be used anymore.

  • Added .fs-* utilities for font-size utilities (with RFS enabled). These use the same scale as HTML’s default headings (1-6, large to small), and can be modified via Sass map.

  • Breaking Renamed .font-weight-* utilities as .fw-* for brevity and consistency.

  • Breaking Renamed .font-style-* utilities as .fst-* for brevity and consistency.

  • Added .d-grid to display utilities and new gap utilities (.gap) for CSS Grid and flexbox layouts.

  • Breaking Removed .rounded-sm and rounded-lg, and introduced a new scale of classes, .rounded-0 to .rounded-3. See #31687.

  • Added new line-height utilities: .lh-1, .lh-sm, .lh-base and .lh-lg. See here.

  • Moved the .d-none utility in our CSS to give it more weight over other display utilities.

  • Extended the .visually-hidden-focusable helper to also work on containers, using :focus-within.

Helpers

  • Breaking Responsive embed helpers have been renamed to ratio helpers with new class names and improved behaviors, as well as a helpful CSS variable.

    • Classes have been renamed to change by to x in the aspect ratio. For example, .ratio-16by9 is now .ratio-16x9.
    • We’ve dropped the .embed-responsive-item and element group selector in favor of a simpler .ratio > * selector. No more class is needed, and the ratio helper now works with any HTML element.
    • The $embed-responsive-aspect-ratios Sass map has been renamed to $aspect-ratios and its values have been simplified to include the class name and the percentage as the key: value pair.
    • CSS variables are now generated and included for each value in the Sass map. Modify the --bs-aspect-ratio variable on the .ratio to create any custom aspect ratio.

  • Breaking “Screen reader” classes are now “visually hidden” classes.

    • Changed the Sass file from scss/helpers/_screenreaders.scss to scss/helpers/_visually-hidden.scss
    • Renamed .sr-only and .sr-only-focusable to .visually-hidden and .visually-hidden-focusable
    • Renamed sr-only() and sr-only-focusable() mixins to visually-hidden() and visually-hidden-focusable().

  • bootstrap-utilities.css now also includes our helpers. Helpers don’t need to be imported in custom builds anymore.

JavaScript

  • Dropped jQuery dependency and rewrote plugins to be in regular JavaScript.

  • Breaking Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we use data-bs-toggle instead of data-toggle.

  • All plugins can now accept a CSS selector as the first argument. You can either pass a DOM element or any valid CSS selector to create a new instance of the plugin:

    var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')

  • popperConfig can be passed as a function that accepts the Bootstrap’s default Popper config as an argument, so that you can merge this default configuration in your way. Applies to dropdowns, popovers, and tooltips.

  • The default value for the fallbackPlacements is changed to ['top', 'right', 'bottom', 'left'] for better placement of Popper elements. Applies to dropdowns, popovers, and tooltips.

  • Removed underscore from public static methods like _getInstance() → getInstance().