bootstrap-utilities

Bootstrap 5.3 实用工具

Bootstrap 提供了丰富的实用工具类，可快速设置样式，无需编写自定义 CSS。这些类通过 Utilities API 生成，并且可以自定义。

间距实用工具

外边距（m-）和内边距（p-）

<div class="m-3">Margin 1rem all sides</div>
<div class="p-3">Padding 1rem all sides</div>


<div class="mt-3">Margin top</div>
<div class="mb-3">Margin bottom</div>
<div class="ms-3">Margin start (left in LTR)</div>
<div class="me-3">Margin end (right in LTR)</div>
<div class="mx-3">Margin horizontal (left + right)</div>
<div class="my-3">Margin vertical (top + bottom)</div>


<div class="px-3 py-2">Horizontal padding 1rem, vertical 0.5rem</div>

间距刻度

类	大小
{m|p}-0	0
{m|p}-1	0.25rem（4px）
{m|p}-2	0.5rem（8px）
{m|p}-3	1rem（16px）
{m|p}-4	1.5rem（24px）
{m|p}-5	3rem（48px）
{m|p}-auto	auto（仅适用于外边距）

响应式间距

<div class="mt-0 mt-md-3 mt-lg-5">
  No margin, 1rem on md, 3rem on lg+
</div>

间隙实用工具（Flexbox/Grid）

<div class="d-flex gap-3">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<div class="d-grid gap-2">
  <button class="btn btn-primary">Button 1</button>
  <button class="btn btn-primary">Button 2</button>
</div>


<div class="d-grid gap-0 row-gap-3 column-gap-3">...</div>

显示实用工具

<div class="d-none">Hidden</div>
<div class="d-inline">Inline</div>
<div class="d-inline-block">Inline-block</div>
<div class="d-block">Block</div>
<div class="d-flex">Flexbox</div>
<div class="d-inline-flex">Inline flex</div>
<div class="d-grid">Grid</div>
<div class="d-table">Table</div>
<div class="d-table-row">Table row</div>
<div class="d-table-cell">Table cell</div>


<div class="d-none d-md-block">Hidden on xs/sm, block on md+</div>
<div class="d-block d-lg-none">Visible until lg</div>


<div class="d-print-none">Hidden in print</div>
<div class="d-none d-print-block">Only visible in print</div>

文本实用工具

对齐方式

<p class="text-start">Left aligned (start)</p>
<p class="text-center">Center aligned</p>
<p class="text-end">Right aligned (end)</p>


<p class="text-start text-md-center text-lg-end">
  Left on xs/sm, center on md, right on lg+
</p>

大小写转换

<p class="text-lowercase">lowercased text</p>
<p class="text-uppercase">UPPERCASED TEXT</p>
<p class="text-capitalize">Capitalized Text</p>

装饰

<a href="#" class="text-decoration-none">No underline</a>
<p class="text-decoration-underline">Underlined text</p>
<p class="text-decoration-line-through">Strikethrough text</p>

换行和溢出

<div class="text-wrap">Text that wraps normally</div>
<div class="text-nowrap">Text that won't wrap</div>
<p class="text-break">Longwordthatwillbreaktopreventoverflow</p>
<p class="text-truncate" style="max-width: 150px;">
  This text is truncated with ellipsis...
</p>

字重和样式

<p class="fw-bold">Bold text</p>
<p class="fw-bolder">Bolder text (relative)</p>
<p class="fw-semibold">Semibold text</p>
<p class="fw-medium">Medium text</p>
<p class="fw-normal">Normal weight</p>
<p class="fw-light">Light text</p>
<p class="fw-lighter">Lighter text (relative)</p>
<p class="fst-italic">Italic text</p>
<p class="fst-normal">Normal style</p>

行高

<p class="lh-1">Line height 1</p>
<p class="lh-sm">Small line height</p>
<p class="lh-base">Base line height</p>
<p class="lh-lg">Large line height</p>

Flexbox 实用工具

方向

<div class="d-flex flex-row">Horizontal</div>
<div class="d-flex flex-row-reverse">Horizontal reversed</div>
<div class="d-flex flex-column">Vertical</div>
<div class="d-flex flex-column-reverse">Vertical reversed</div>

主轴对齐方式

<div class="d-flex justify-content-start">Start</div>
<div class="d-flex justify-content-end">End</div>
<div class="d-flex justify-content-center">Center</div>
<div class="d-flex justify-content-between">Space between</div>
<div class="d-flex justify-content-around">Space around</div>
<div class="d-flex justify-content-evenly">Space evenly</div>

交叉轴对齐方式

<div class="d-flex align-items-start">Top</div>
<div class="d-flex align-items-end">Bottom</div>
<div class="d-flex align-items-center">Center</div>
<div class="d-flex align-items-baseline">Baseline</div>
<div class="d-flex align-items-stretch">Stretch</div>

自身对齐方式

<div class="align-self-start">Top</div>
<div class="align-self-center">Center</div>
<div class="align-self-end">Bottom</div>

Flex 换行

<div class="d-flex flex-wrap">Wrap</div>
<div class="d-flex flex-nowrap">No wrap</div>
<div class="d-flex flex-wrap-reverse">Wrap reverse</div>

Flex 增长/收缩

<div class="flex-grow-0">Don't grow</div>
<div class="flex-grow-1">Grow to fill</div>
<div class="flex-shrink-0">Don't shrink</div>
<div class="flex-shrink-1">Can shrink</div>
<div class="flex-fill">Fill available space</div>

顺序

<div class="order-0">First</div>
<div class="order-1">Second</div>
<div class="order-2">Third</div>
<div class="order-first">Very first (-1)</div>
<div class="order-last">Very last (6)</div>

背景实用工具

<div class="bg-primary">Primary</div>
<div class="bg-secondary">Secondary</div>
<div class="bg-success">Success</div>
<div class="bg-danger">Danger</div>
<div class="bg-warning">Warning</div>
<div class="bg-info">Info</div>
<div class="bg-light">Light</div>
<div class="bg-dark">Dark</div>
<div class="bg-body">Body</div>
<div class="bg-body-secondary">Body secondary</div>
<div class="bg-body-tertiary">Body tertiary</div>
<div class="bg-white">White</div>
<div class="bg-black">Black</div>
<div class="bg-transparent">Transparent</div>


<div class="bg-primary bg-opacity-75">75%</div>
<div class="bg-primary bg-opacity-50">50%</div>
<div class="bg-primary bg-opacity-25">25%</div>
<div class="bg-primary bg-opacity-10">10%</div>


<div class="bg-primary bg-gradient">Gradient</div>

文本颜色实用工具

<p class="text-primary">Primary text</p>
<p class="text-secondary">Secondary text</p>
<p class="text-success">Success text</p>
<p class="text-danger">Danger text</p>
<p class="text-warning">Warning text</p>
<p class="text-info">Info text</p>
<p class="text-muted">Muted text</p>
<p class="text-body">Body text</p>
<p class="text-body-secondary">Body secondary</p>
<p class="text-body-tertiary">Body tertiary</p>
<p class="text-body-emphasis">Body emphasis</p>
<p class="text-black">Black text</p>
<p class="text-white bg-dark">White text</p>


<p class="text-primary text-opacity-75">75% opacity</p>
<p class="text-primary text-opacity-50">50% opacity</p>
<p class="text-primary text-opacity-25">25% opacity</p>

边框实用工具

<div class="border">All sides</div>
<div class="border-top">Top</div>
<div class="border-end">End</div>
<div class="border-bottom">Bottom</div>
<div class="border-start">Start</div>


<div class="border-0">No border</div>
<div class="border-top-0">No top border</div>


<div class="border border-primary">Primary</div>
<div class="border border-success">Success</div>
<div class="border border-danger">Danger</div>


<div class="border border-1">1px</div>
<div class="border border-2">2px</div>
<div class="border border-3">3px</div>
<div class="border border-4">4px</div>
<div class="border border-5">5px</div>


<div class="rounded">Rounded</div>
<div class="rounded-0">No radius</div>
<div class="rounded-1">Small radius</div>
<div class="rounded-2">Default radius</div>
<div class="rounded-3">Large radius</div>
<div class="rounded-4">XL radius</div>
<div class="rounded-5">XXL radius</div>
<div class="rounded-circle">Circle</div>
<div class="rounded-pill">Pill</div>
<div class="rounded-top">Top only</div>
<div class="rounded-end">End only</div>
<div class="rounded-bottom">Bottom only</div>
<div class="rounded-start">Start only</div>

阴影实用工具

<div class="shadow-none">No shadow</div>
<div class="shadow-sm">Small shadow</div>
<div class="shadow">Regular shadow</div>
<div class="shadow-lg">Large shadow</div>

尺寸实用工具

宽度

<div class="w-25">25% width</div>
<div class="w-50">50% width</div>
<div class="w-75">75% width</div>
<div class="w-100">100% width</div>
<div class="w-auto">Auto width</div>
<div class="mw-100">Max-width 100%</div>
<div class="vw-100">100vw</div>
<div class="min-vw-100">Min 100vw</div>

高度

<div class="h-25">25% height</div>
<div class="h-50">50% height</div>
<div class="h-75">75% height</div>
<div class="h-100">100% height</div>
<div class="h-auto">Auto height</div>
<div class="mh-100">Max-height 100%</div>
<div class="vh-100">100vh</div>
<div class="min-vh-100">Min 100vh</div>

定位实用工具

定位值

<div class="position-static">Static (default)</div>
<div class="position-relative">Relative</div>
<div class="position-absolute">Absolute</div>
<div class="position-fixed">Fixed</div>
<div class="position-sticky">Sticky</div>

位置

<div class="position-absolute top-0 start-0">Top left</div>
<div class="position-absolute top-0 end-0">Top right</div>
<div class="position-absolute bottom-0 start-0">Bottom left</div>
<div class="position-absolute bottom-0 end-0">Bottom right</div>
<div class="position-absolute top-50 start-50">Center (needs transform)</div>

使用 Translate 居中

<div class="position-absolute top-50 start-50 translate-middle">
  Perfectly centered
</div>


<div class="position-absolute start-50 translate-middle-x">
  Horizontally centered
</div>


<div class="position-absolute top-50 translate-middle-y">
  Vertically centered
</div>

常见模式：徽章定位

<button class="btn btn-primary position-relative">
  Notifications
  <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill bg-danger">
    99+
  </span>
</button>

溢出实用工具

<div class="overflow-auto">Auto</div>
<div class="overflow-hidden">Hidden</div>
<div class="overflow-visible">Visible</div>
<div class="overflow-scroll">Scroll</div>

<div class="overflow-x-auto">Horizontal auto</div>
<div class="overflow-x-hidden">Horizontal hidden</div>
<div class="overflow-y-auto">Vertical auto</div>
<div class="overflow-y-hidden">Vertical hidden</div>

不透明度实用工具

<div class="opacity-100">100%</div>
<div class="opacity-75">75%</div>
<div class="opacity-50">50%</div>
<div class="opacity-25">25%</div>
<div class="opacity-0">0%</div>

可见性实用工具

<div class="visible">Visible</div>
<div class="invisible">Invisible (takes space)</div>

Z-Index 实用工具

<div class="z-n1">-1</div>
<div class="z-0">0</div>
<div class="z-1">1</div>
<div class="z-2">2</div>
<div class="z-3">3</div>

对象适配实用工具

<img class="object-fit-contain" src="...">
<img class="object-fit-cover" src="...">
<img class="object-fit-fill" src="...">
<img class="object-fit-scale" src="...">
<img class="object-fit-none" src="...">

交互实用工具

<div class="user-select-all">Select all on click</div>
<div class="user-select-auto">Default selection</div>
<div class="user-select-none">Cannot select</div>
<div class="pe-none">Pointer events none</div>
<div class="pe-auto">Pointer events auto</div>

浮动实用工具

浮动实用工具可将元素定位到其容器的左侧或右侧，让文本环绕元素显示。

<div class="float-start">Float start (left in LTR)</div>
<div class="float-end">Float end (right in LTR)</div>
<div class="float-none">No float</div>


<div class="float-sm-start">Float start on sm+</div>
<div class="float-md-end">Float end on md+</div>
<div class="float-lg-none">No float on lg+</div>

类	说明
float-start	向左浮动（LTR）
float-end	向右浮动（LTR）
float-none	移除浮动

响应式：float-{breakpoint}-{start|end|none}

注意：现代布局通常使用 flexbox 或 grid，而不是浮动。浮动仍适用于让文本环绕图像。

垂直对齐实用工具

控制行内、行内块、行内表格及表格单元格元素的垂直对齐方式。

<span class="align-baseline">baseline</span>
<span class="align-top">top</span>
<span class="align-middle">middle</span>
<span class="align-bottom">bottom</span>
<span class="align-text-top">text-top</span>
<span class="align-text-bottom">text-bottom</span>

类	对齐方式
align-baseline	基线（默认）
align-top	行顶端
align-middle	行中部
align-bottom	行底端
align-text-top	父元素字体顶部
align-text-bottom	父元素字体底部

注意：这些类适用于行内/行内块元素和表格单元格，不适用于块级元素。对于块级元素的垂直对齐，请使用 flexbox（align-items-*）。

链接实用工具

使用不透明度、下划线颜色、偏移和悬停效果设置链接样式。此功能于 Bootstrap 5.3 中新增。

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


<a href="#" class="link-opacity-50-hover">50% on hover</a>


<a href="#" class="link-underline-primary">Primary underline</a>
<a href="#" class="link-underline-secondary">Secondary underline</a>
<a href="#" class="link-underline-success">Success underline</a>


<a href="#" class="link-offset-1">1 offset</a>
<a href="#" class="link-offset-2">2 offset</a>
<a href="#" class="link-offset-3">3 offset</a>


<a href="#" class="link-underline-opacity-0">No underline</a>
<a href="#" class="link-underline-opacity-25">25% underline</a>
<a href="#" class="link-underline-opacity-50">50% underline</a>


<a href="#" class="link-offset-2 link-underline-opacity-25 link-underline-opacity-100-hover">
  Styled link
</a>

类	说明
link-opacity-{10|25|50|75|100}	链接文本不透明度
link-opacity-{value}-hover	悬停时的不透明度
link-underline-{color}	下划线颜色
link-offset-{1|2|3}	下划线距离
link-underline-opacity-{0|10|25|50|75|100}	下划线不透明度

Utilities API

Bootstrap 的实用工具通过基于 Sass 的 API 生成，支持全面自定义。

API 结构

每个工具都定义为一个映射，包含以下关键选项：

选项	描述
property	CSS 属性名称（必需）
values	值列表或映射（必需）
class	自定义类前缀（可选）
responsive	生成响应式变体（默认值：false）
print	生成打印变体（默认值：false）
state	生成状态变体，例如 :hover
css-var	输出为 CSS 变量，而非规则
css-variable-name	自定义 CSS 变量名称（与 css-var 搭配使用）
local-vars	局部 CSS 变量映射
rfs	启用流体缩放（默认值：false）
rtl	纳入 RTL 输出（默认值：true）

注意：默认情况下，所有工具都包含 !important。将 $enable-important-utilities: false 设为全局禁用。

添加自定义工具

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab grabbing not-allowed
    )
  )
);

@import "bootstrap/scss/utilities/api";

修改现有工具

// Add responsive variants to an existing utility
$utilities: map-merge(
  $utilities,
  (
    "overflow": map-merge(
      map-get($utilities, "overflow"),
      (responsive: true)
    )
  )
);

移除工具

// Remove entirely
$utilities: map-remove($utilities, "float");

// Or set to null
$utilities: map-merge($utilities, ("float": null));

常见模式

适用于实际场景的常用工具组合。

居中容器（全视口）

<div class="d-flex justify-content-center align-items-center min-vh-100">
  <div class="text-center">
    <h1>Perfectly Centered</h1>
    <p>Both horizontally and vertically</p>
  </div>
</div>

粘性页脚布局

<div class="d-flex flex-column min-vh-100">
  <header class="bg-dark text-white p-3">Header</header>
  <main class="flex-grow-1 p-3">Main content</main>
  <footer class="bg-body-secondary p-3">Footer stays at bottom</footer>
</div>

带间距和阴影的卡片

<div class="card shadow-sm border-0 rounded-3">
  <div class="card-body p-4">
    <h5 class="card-title mb-3">Title</h5>
    <p class="card-text text-muted mb-0">Content</p>
  </div>
</div>

响应式隐藏/显示

<div class="d-none d-md-block">Desktop only</div>


<div class="d-block d-md-none">Mobile only</div>

图标与文本对齐

<div class="d-flex align-items-center gap-2">
  <svg>...</svg>
  <span>Text aligned with icon</span>
</div>

何时使用工具而非自定义 CSS

场景	推荐方法
单次间距调整	工具类（mt-3、p-4）
统一的组件样式	自定义组件类
响应式显示/隐藏	显示工具（d-none d-md-block）
复杂的悬停/焦点状态	自定义 CSS
Bootstrap 尺度中没有的值	通过 Utilities API 扩展或使用自定义 CSS
重复模式（3 次以上）	提取为自定义类
快速原型	使用工具提高速度
生产环境中的组件	考虑提取重复使用的工具

经验法则：如果多个元素都应用了相同的 4 个以上工具组合，请考虑创建自定义类。

更多资源

参考文件

• references/utilities-reference.md - 完整的工具类参考
• references/api-customization.md - 高级 Sass 自定义示例

示例文件

• examples/card-layout.html - 带间距、阴影和边框的卡片样式
• examples/responsive-utilities.html - 响应式显示和间距模式
• examples/flex-centering.html - Flexbox 居中技巧