bootstrap-helpers

Bootstrap 5.3 辅助工具

Bootstrap 提供了适用于常见实用模式的辅助类，用于扩展基础实用类。

清除浮动

清除容器内的浮动：

<div class="clearfix">
  <button class="btn btn-secondary float-start">Left float</button>
  <button class="btn btn-secondary float-end">Right float</button>
</div>

颜色与背景

组合使用颜色和背景辅助工具，以确保对比度适当：

<div class="text-bg-primary p-3">Primary with proper contrast</div>
<div class="text-bg-secondary p-3">Secondary</div>
<div class="text-bg-success p-3">Success</div>
<div class="text-bg-danger p-3">Danger</div>
<div class="text-bg-warning p-3">Warning</div>
<div class="text-bg-info p-3">Info</div>
<div class="text-bg-light p-3">Light</div>
<div class="text-bg-dark p-3">Dark</div>

这些辅助工具会自动确保文字颜色具有适当的对比度。

彩色链接

带悬停状态的链接颜色：

<a href="#" class="link-primary">Primary link</a>
<a href="#" class="link-secondary">Secondary link</a>
<a href="#" class="link-success">Success link</a>
<a href="#" class="link-danger">Danger link</a>
<a href="#" class="link-warning">Warning link</a>
<a href="#" class="link-info">Info link</a>
<a href="#" class="link-light">Light link</a>
<a href="#" class="link-dark">Dark link</a>
<a href="#" class="link-body-emphasis">Body emphasis link</a>


<a href="#" class="link-primary link-opacity-10">10% opacity</a>
<a href="#" class="link-primary link-opacity-25">25% opacity</a>
<a href="#" class="link-primary link-opacity-50">50% opacity</a>
<a href="#" class="link-primary link-opacity-75">75% opacity</a>
<a href="#" class="link-primary link-opacity-100">100% opacity</a>



<a href="#" class="link-underline link-underline-opacity-50">Base underline with 50% opacity</a>
<a href="#" class="link-underline-primary link-underline-opacity-25">Primary underline at 25%</a>


<a href="#" class="link-primary link-underline link-underline-opacity-0">No underline</a>
<a href="#" class="link-primary link-underline link-underline-opacity-10">Light underline</a>


<a href="#" class="link-primary link-offset-2">Offset underline</a>
<a href="#" class="link-primary link-offset-3">More offset</a>

悬停变体

链接实用类包含悬停变体，可实现动态效果：

<a href="#" class="link-primary link-opacity-50 link-opacity-100-hover">Brightens on hover</a>


<a href="#" class="link-primary link-underline-opacity-0 link-underline-opacity-100-hover">Underline on hover</a>


<a href="#" class="link-primary link-offset-2 link-offset-3-hover">Offset increases on hover</a>


<a href="#" class="link-offset-2 link-offset-3-hover link-underline link-underline-opacity-0 link-underline-opacity-75-hover">
  Underline appears on hover
</a>

焦点环

自定义焦点环样式：

<a href="#" class="d-inline-flex focus-ring py-1 px-2 text-decoration-none border rounded-2">
  Custom focus ring
</a>


<a href="#" class="d-inline-flex focus-ring focus-ring-primary">Primary</a>
<a href="#" class="d-inline-flex focus-ring focus-ring-secondary">Secondary</a>
<a href="#" class="d-inline-flex focus-ring focus-ring-success">Success</a>
<a href="#" class="d-inline-flex focus-ring focus-ring-danger">Danger</a>


<a href="#" class="d-inline-flex focus-ring" style="--bs-focus-ring-color: rgba(118, 169, 250, .5)">
  Custom color
</a>

图标链接

为包含图标的链接设置样式：

<a class="icon-link" href="#">
  <svg class="bi" aria-hidden="true"><use xlink:href="#box-seam"></use></svg>
  Icon link
</a>

<a class="icon-link" href="#">
  Icon link
  <svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
</a>


<a class="icon-link icon-link-hover" href="#">
  Icon link
  <svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
</a>


<a class="icon-link icon-link-hover" style="--bs-icon-link-transform: translate3d(0, -.125rem, 0);" href="#">
  <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"></use></svg>
  Icon link
</a>

定位

适用于常见模式的定位辅助工具：

固定定位

<div class="fixed-top">Fixed to top</div>
<div class="fixed-bottom">Fixed to bottom</div>

粘性定位

<div class="sticky-top">Sticky top</div>
<div class="sticky-sm-top">Sticky top on sm+</div>
<div class="sticky-md-top">Sticky top on md+</div>
<div class="sticky-lg-top">Sticky top on lg+</div>
<div class="sticky-xl-top">Sticky top on xl+</div>
<div class="sticky-xxl-top">Sticky top on xxl+</div>

<div class="sticky-bottom">Sticky bottom</div>
<div class="sticky-sm-bottom">Sticky bottom on sm+</div>
<div class="sticky-md-bottom">Sticky bottom on md+</div>
<div class="sticky-lg-bottom">Sticky bottom on lg+</div>
<div class="sticky-xl-bottom">Sticky bottom on xl+</div>
<div class="sticky-xxl-bottom">Sticky bottom on xxl+</div>

比例

保持嵌入内容和视频的宽高比：

<div class="ratio ratio-16x9">
  <iframe src="https://www.youtube.com/embed/..." title="YouTube video"></iframe>
</div>


<div class="ratio ratio-21x9">
  <iframe src="..."></iframe>
</div>


<div class="ratio ratio-4x3">
  <iframe src="..."></iframe>
</div>


<div class="ratio ratio-1x1">
  <iframe src="..."></iframe>
</div>


<div class="ratio" style="--bs-aspect-ratio: 50%;">
  <iframe src="..."></iframe>
</div>

堆叠

快速创建 flexbox 布局：

垂直堆叠（vstack）

<div class="vstack gap-3">
  <div class="p-2">First item</div>
  <div class="p-2">Second item</div>
  <div class="p-2">Third item</div>
</div>


<div class="vstack gap-2">
  <button class="btn btn-secondary">Top</button>
  <button class="btn btn-secondary mt-auto">Bottom</button>
</div>

水平堆叠（hstack）

<div class="hstack gap-3">
  <div class="p-2">First</div>
  <div class="p-2">Second</div>
  <div class="p-2">Third</div>
</div>


<div class="hstack gap-3">
  <button class="btn btn-secondary">Left</button>
  <div class="vr"></div>  
  <button class="btn btn-secondary ms-auto">Right</button>
</div>


<div class="hstack gap-3">
  <input class="form-control me-auto" type="text" placeholder="Add your item here...">
  <button type="button" class="btn btn-secondary">Submit</button>
  <div class="vr"></div>
  <button type="button" class="btn btn-outline-danger">Reset</button>
</div>

浏览器支持说明： 在低于 14.5 的 Safari 版本中，flexbox 的间距实用类（.gap-*）尚未得到完全支持。网格布局不受影响。若要获得更广泛的浏览器支持，可考虑改用外边距实用类。

链接扩展点击区域

使整个容器都可点击：

<div class="card" style="width: 18rem;">
  <img src="..." class="card-img-top" alt="...">
  <div class="card-body">
    <h5 class="card-title">Card with stretched link</h5>
    <p class="card-text">Some text that will appear.</p>
    <a href="#" class="stretched-link">Go somewhere</a>
  </div>
</div>


<div class="row g-0 bg-body-secondary position-relative">
  <div class="col-md-6">
    <img src="..." class="w-100" alt="...">
  </div>
  <div class="col-md-6 p-4">
    <h5>Columns with stretched link</h5>
    <a href="#" class="stretched-link">Go somewhere</a>
  </div>
</div>

说明： 父元素必须设置 position: relative（卡片默认已设置此属性）。

识别包含块： 如果扩展点击区域的链接未按预期工作，请检查父元素是否设置了以下同样会创建包含块的 CSS 属性：transform、perspective、filter（仅限 Firefox），或者将 will-change 设置为 transform 或 perspective。

文本截断

使用省略号截断长文本：

<div class="text-truncate" style="max-width: 150px;">
  This text is too long and will be truncated with an ellipsis.
</div>


<span class="d-inline-block text-truncate" style="max-width: 150px;">
  This text is truncated.
</span>

垂直分隔线

垂直分隔线：

<div class="vr"></div>


<div class="d-flex" style="height: 200px;">
  <div class="vr"></div>
</div>


<div class="hstack gap-3">
  <div>Item 1</div>
  <div class="vr"></div>
  <div>Item 2</div>
  <div class="vr"></div>
  <div>Item 3</div>
</div>

视觉隐藏

视觉上隐藏内容，但仍让屏幕阅读器能够访问：

<h2 class="visually-hidden">Title for screen readers</h2>


<a class="visually-hidden-focusable" href="#main-content">Skip to main content</a>

使用场景：

• 跳过导航链接
• 视觉上下文足够时使用的表单标签
• 图标/图片的补充说明
• 用于构建文档结构的标题

Sass 混入可用于自定义类：

@import "bootstrap/scss/mixins/visually-hidden";

.custom-sr-only {
  @include visually-hidden;
}

Sass 自定义

许多辅助工具支持通过 Sass 变量在构建时进行自定义：

• 焦点环：$focus-ring-width、$focus-ring-opacity、$focus-ring-blur
• 图标链接：$icon-link-gap、$icon-link-icon-size、$icon-link-icon-transform
• 比例：用于自定义宽高比的 $aspect-ratios 映射

其他资源

参考文件

• references/helpers-reference.md - 完整的辅助类参考及 Sass 自定义选项

示例文件

• examples/accessibility-patterns.html - 视觉隐藏、焦点环、跳过链接和屏幕阅读器实用类
• examples/link-helpers-patterns.html - 彩色链接、图标链接、扩展点击区域的链接和链接实用类
• examples/position-layout-patterns.html - 固定和粘性定位模式
• examples/ratio-embed-patterns.html - 响应式视频嵌入和宽高比实用类
• examples/stack-patterns.html - 全面的 vstack/hstack 模式，包括各种间距