实用程序 API

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

在此页面上

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

$utilities 映射包含我们所有的实用程序，如果存在，稍后会与您的自定义 $utilities 映射合并。实用程序映射包含一个键控实用程序组列表，该列表接受以下选项

选项	类型	默认值	说明
`属性`	必需	–	属性的名称，可以是字符串或字符串数组（例如，水平填充或边距）。
`值`	必需	–	值列表或映射（如果您不希望类名与值相同）。如果 `null` 用作映射键，则 `class` 不会添加到类名之前。
`类`	可选	null	生成类的名称。如果未提供且 `property` 是字符串数组，则 `class` 将默认为 `property` 数组的第一个元素。如果未提供且 `property` 是字符串，则 `values` 键用于 `class` 名称。
`css-var`	可选	`false`	布尔值，用于生成 CSS 变量而不是 CSS 规则。
`css-variable-name`	可选	null	规则集内 CSS 变量的自定义未加前缀的名称。
`local-vars`	可选	null	除了 CSS 规则之外，还要生成的本地 CSS 变量映射。
`状态`	可选	null	要生成的伪类变体列表（例如，`:hover` 或 `:focus`）。
`响应式`	可选	`false`	指示是否应生成响应式类的布尔值。
`rfs`	可选	`false`	启用使用 RFS 进行流体缩放的布尔值。
`print`	可选	`false`	指示是否需要生成打印类别的布尔值。
`rtl`	可选	`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";

移除实用程序

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

@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";

你还可以使用 Sass 函数 `map-merge()`，并将组键设置为 `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";

添加、移除、修改

你可以使用 Sass 函数 `map-merge()` 一次添加、移除和修改多个实用程序。以下是如何将前面的示例合并到一个更大的映射中。

@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` 控制指令。