API

工具类 API 是一个基于 Sass 的工具，用于生成工具类。

本页目录

Bootstrap 工具是通过我们的工具 API 生成的，可以通过 Sass 修改或扩展我们默认的工具类集合。我们的工具 API 基于一系列 Sass 映射和函数，用于生成具有各种选项的类族。如果你不熟悉 Sass 映射，请查阅官方 Sass 文档以入门。

$utilities Map包含了我们所有的工具，并且如果存在的话，之后会与你的自定义 $utilities Map合并。工具Map包含了一个带键的工具组列表，这些工具组接受以下选项：

选项	类型	默认值	描述
`property`	必填	–	属性的名称，这可以是一个字符串或字符串数组（例如，水平内边距或外边距）。
`values`	必填	–	值的列表，或者如果你不希望类名与值相同，可以使用映射。如果 `null` 用作Map键， `class` 不会被加在类名之前。
`class`	可选	null	生成类的名称。如果未提供，并且 `property` 是一个字符串数组， `class` 将默认为第一个元素 `property` 数组。如果未提供，并且 `property` 是一个字符串，那个 `values` 钥匙用于 `class` 名字。
`css-var`	可选	`false`	布尔值，用于生成 CSS 变量而不是 CSS 规则。
`css-variable-name`	可选	null	规则集中 CSS 变量的自定义无前缀名称。
`local-vars`	可选	null	本地 CSS 变量映射，用于生成除 CSS 规则之外的内容。
`state`	可选	null	伪类变体列表（例如， `:hover` 或 `:focus`) 生成。
`responsive`	可选	`false`	布尔值，指示是否应生成响应式类。
`rfs`	可选	`false`	布尔值以启用使用 RFS 的流体重新缩放.
`print`	可选	`false`	布尔值，指示是否需要生成打印类。
`rtl`	可选	`true`	布尔值，指示是否应将工具类保持为从右到左（RTL）模式。

API 解释

所有实用变量都被添加到 $utilities 我们内部的变量 _utilities.scss 样式表。每组工具的样子大致如下：

$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

作为一个Map，就像使用 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,
  ),
);

添加工具类

可以向默认设置添加新的工具类 $utilities 带有…的Map map-merge. 确保我们的必要 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";

修改工具类

修改默认中的现有工具类 $utilities 带有…的Map map-get 和 map-merge 函数。在下面的例子中，我们正在向...添加一个额外的值 width 工具类。从初始开始 map-merge 然后指定你想修改的工具类。从那里，获取嵌套的 "width" 带有……的Map map-get 访问和修改该工具类的选项和值。

@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";
// Remove multiple utilities with a comma-separated list
$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 函数一次性添加、删除和修改许多工具类。以下是如何将前面的示例合并为一个更大的 map 的方法。

@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 */

由于……，这在 RTL 中不会输出任何内容 RTLCSS remove 控制指令.