通用API（Utility API）

通用API（Utility API），也翻译成实用程序 API，是一种基于 Sass 的工具，用于生成实用程序类。

On this page

Bootstrap 实用程序由我们的实用程序 API 生成，可用于通过 Sass 修改或扩展我们的默认实用程序类集。我们的实用程序 API 基于一系列 Sass 映射和函数，用于生成带有各种选项的类族。如果您不熟悉 Sass 映射，请阅读 Sass 官方文档开始学习。

$utilities 映射包含我们的所有实用程序，随后将与您自定义的 $utilities 映射（如果存在）合并。实用程序映射包含实用程序组的键控列表，可接受以下选项：

Option	Type	Default value	Description
`property`	Required	–	属性名称，可以是字符串或字符串数组（如水平衬垫或边距）。
`values`	Required	–	值的列表，如果不希望类名与值相同，则使用映射。如果使用 `null` 作为映射关键字，则不会在类名前加上 `class`。
`class`	Optional	null	生成类的名称。如果未提供且 `property` 是字符串数组，`class` 将默认为 `property` 数组的第一个元素。如果未提供，且 `property` 是字符串，则 `values` 键将用于 `class` 名称。
`css-var`	Optional	`false`	布尔值，用于生成 CSS 变量而不是 CSS 规则。
`css-variable-name`	Optional	null	规则集中 CSS 变量的自定义非前缀名称。
`local-vars`	Optional	null	除 CSS 规则外还需生成的本地 CSS 变量映射。
`state`	Optional	null	要生成的伪类变体（如 `:hover` 或 `:focus`）列表。
`responsive`	Optional	`false`	布尔值，表示是否应生成响应类。
`rfs`	Optional	`false`	布尔值，用于启用使用 RFS 进行流体再缩放功能。
`print`	Optional	`false`	布尔值，表示是否需要生成打印类。
`rtl`	Optional	`true`	布尔值，表示实用程序是否应保留在 RTL 中。

API 解释

所有实用程序变量都会添加到我们的 _utilities.scss 样式表中的 $utilities 变量中。每组实用程序看起来是这样的：

$utilities: (
  "opacity": (
    property: opacity,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

其中输出以下内容：

.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

属性

任何实用程序都必须设置所需的 property 键，并且必须包含一个有效的 CSS 属性。该属性将在生成的实用程序规则集中使用。如果省略了 class 键，它也将作为默认的类名。请看 text-decoration 工具：

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

输出：

.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }

值

使用 values 键指定在生成的类名和规则中应使用指定的 property 值。可以是列表或映射（在实用程序或 Sass 变量中设置）。

以列表形式出现，如 text-decoration实用程序:

values: none underline line-through

作为映射，就像使用 opacity 实用程序一样：

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

作为设置列表或映射的 Sass 变量，如我们的 position 实用程序:

values: $position-values

类

使用 class 选项可更改编译 CSS 中使用的类前缀。例如，将 .opacity-* 改为 .o-*：

$utilities: (
  "opacity": (
    property: opacity,
    class: o,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

输出:

.o-0 { opacity: 0 !important; }
.o-25 { opacity: .25 !important; }
.o-50 { opacity: .5 !important; }
.o-75 { opacity: .75 !important; }
.o-100 { opacity: 1 !important; }

如果 class: null, 则为每个 values 键生成类别：

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

输出:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

CSS 变量实用程序

将 css-var 布尔值选项设为 true，API 就会为给定的选择器生成本地 CSS 变量，而不是通常的 property: value 规则。添加可选的 css-variable-name 以设置与类名不同的 CSS 变量名。

请看我们的 .text-opacity-* 工具。如果我们添加 css-variable-name 选项，就会得到自定义输出。

$utilities: (
  "text-opacity": (
    css-var: true,
    css-variable-name: text-alpha,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

输出:

.text-opacity-25 { --bs-text-alpha: .25; }
.text-opacity-50 { --bs-text-alpha: .5; }
.text-opacity-75 { --bs-text-alpha: .75; }
.text-opacity-100 { --bs-text-alpha: 1; }

本地 CSS 变量

使用 local-vars 选项指定一个 Sass 映射，该映射将在实用程序类的规则集中生成本地 CSS 变量。请注意，在生成的 CSS 规则中使用这些本地 CSS 变量可能需要额外的工作。例如，请看我们的 .bg-* 工具：

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

输出:

.bg-primary {
  --bs-bg-opacity: 1;
  background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}

状态

使用 state 选项可生成各种伪类。伪类的例子有 :hover和:focus。如果提供了状态列表，就会为该伪类创建类名。例如，要改变悬停时的不透明度，添加 state: hover，编译后的 CSS 中就会出现 .opacity-hover:hover。

需要多个伪类？使用空格分隔的状态列表： state: hover focus.

$utilities: (
  "opacity": (
    property: opacity,
    class: opacity,
    state: hover,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

输出:

.opacity-0-hover:hover { opacity: 0 !important; }
.opacity-25-hover:hover { opacity: .25 !important; }
.opacity-50-hover:hover { opacity: .5 !important; }
.opacity-75-hover:hover { opacity: .75 !important; }
.opacity-100-hover:hover { opacity: 1 !important; }

响应式

添加 responsive 布尔值，在所有断点生成响应式实用程序（例如 .opacity-md-25）。

$utilities: (
  "opacity": (
    property: opacity,
    responsive: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

输出：

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

@media (min-width: 576px) {
  .opacity-sm-0 { opacity: 0 !important; }
  .opacity-sm-25 { opacity: .25 !important; }
  .opacity-sm-50 { opacity: .5 !important; }
  .opacity-sm-75 { opacity: .75 !important; }
  .opacity-sm-100 { opacity: 1 !important; }
}

@media (min-width: 768px) {
  .opacity-md-0 { opacity: 0 !important; }
  .opacity-md-25 { opacity: .25 !important; }
  .opacity-md-50 { opacity: .5 !important; }
  .opacity-md-75 { opacity: .75 !important; }
  .opacity-md-100 { opacity: 1 !important; }
}

@media (min-width: 992px) {
  .opacity-lg-0 { opacity: 0 !important; }
  .opacity-lg-25 { opacity: .25 !important; }
  .opacity-lg-50 { opacity: .5 !important; }
  .opacity-lg-75 { opacity: .75 !important; }
  .opacity-lg-100 { opacity: 1 !important; }
}

@media (min-width: 1200px) {
  .opacity-xl-0 { opacity: 0 !important; }
  .opacity-xl-25 { opacity: .25 !important; }
  .opacity-xl-50 { opacity: .5 !important; }
  .opacity-xl-75 { opacity: .75 !important; }
  .opacity-xl-100 { opacity: 1 !important; }
}

@media (min-width: 1400px) {
  .opacity-xxl-0 { opacity: 0 !important; }
  .opacity-xxl-25 { opacity: .25 !important; }
  .opacity-xxl-50 { opacity: .5 !important; }
  .opacity-xxl-75 { opacity: .75 !important; }
  .opacity-xxl-100 { opacity: 1 !important; }
}

打印

启用 print 选项还将生成用于打印的实用类，这些实用类仅应用于@media print { ... } 媒体查询。

$utilities: (
  "opacity": (
    property: opacity,
    print: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

输出:

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

@media print {
  .opacity-print-0 { opacity: 0 !important; }
  .opacity-print-25 { opacity: .25 !important; }
  .opacity-print-50 { opacity: .5 !important; }
  .opacity-print-75 { opacity: .75 !important; }
  .opacity-print-100 { opacity: 1 !important; }
}

重要程度

API 生成的所有实用程序都包含 !important，以确保它们按预期覆盖组件和修改器类。您可以使用 $enable-important-utilities 变量（默认为 true）在全局范围内切换此设置。

使用 API

现在，您已经熟悉了实用程序 API 的工作原理，可以学习如何添加自己的自定义类和修改我们的默认实用程序。

覆盖实用程序

使用相同的键重写现有的实用程序。例如，如果您想要额外的响应式溢出实用程序类，可以这样做：

$utilities: (
  "overflow": (
    responsive: true,
    property: overflow,
    values: visible hidden scroll auto,
  ),
);

添加实用程序

新的实用程序可以通过 map-merge 添加到默认的 $utilities 映射中。首先确保导入了所需的 Sass 文件和 _utilities.scss，然后使用 map-merge 添加其他实用程序。例如，下面是如何添加一个有三个值的响应式cursor 工具。

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

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

修改实用程序

使用 map-get 和 map-merge 函数修改默认 $utilities 映射中的现有实用程序。在下面的示例中，我们要为 width 工具添加一个附加值。从初始的 map-merge 开始，然后指定要修改的实用程序。然后，使用 map-get 获取嵌套的 "width" 映射，访问并修改实用程序的选项和值。

@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,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

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

启用响应式

您可以为默认情况下不响应的现有实用程序启用响应类。例如，要使 border 类响应：

@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, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

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

这将为每个断点生成 .border 和 .border-0 的响应变化。生成的 CSS 将如下所示：

.border { ... }
.border-0 { ... }

@media (min-width: 576px) {
  .border-sm { ... }
  .border-sm-0 { ... }
}

@media (min-width: 768px) {
  .border-md { ... }
  .border-md-0 { ... }
}

@media (min-width: 992px) {
  .border-lg { ... }
  .border-lg-0 { ... }
}

@media (min-width: 1200px) {
  .border-xl { ... }
  .border-xl-0 { ... }
}

@media (min-width: 1400px) {
  .border-xxl { ... }
  .border-xxl-0 { ... }
}

重命名实用程序

缺少 v4 实用程序，或使用其他命名约定？实用程序 API 可用于覆盖给定实用程序的 class –例如，将.ms-*实用程序重命名为旧式的.ml-*：

@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, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

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

移除实用程序

使用map-remove() Sass 函数移除任何默认实用程序。

@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-remove($utilities, "width", "float");

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

您也可以使用 map-merge() Sass 函数并将组键设置为 null 以移除实用程序。

@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,
  (
    "width": null
  )
);

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

添加, 移除, 修改

使用map-merge() Sass 函数，你可以一次添加、移除和修改许多实用工具。下面是如何将前面的示例合并成一个更大的地图。

@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,
  (
    // Remove the `width` utility
    "width": null,

    // Make an existing utility responsive
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Add new utilities
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

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

删除 RTL 中的实用程序

某些边缘情况会导致 RTL 风格设计困难，例如阿拉伯语中的换行符。因此，可以通过将 rtl 选项设置为 false，从 RTL 输出中删除实用程序：

$utilities: (
  "word-wrap": (
    property: word-wrap word-break,
    class: text,
    values: (break: break-word),
    rtl: false
  ),
);

输出:

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

由于使用了 RTLCSS remove 控制指令，这在 RTL 中不会输出任何内容。