实用程序 API

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

内容提要

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

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

选项	类型	默认值	描述
`property`	Required	–	属性的名称，可以是字符串或字符串数组（例如，水平内边距或外边距）。
`values`	Required	–	值的列表，如果您不希望类名与值相同，则为map。如果映射键为 `null` ，则不编译。
`class`	Optional	null	生成的类的名称。如果未提供且 `property` 是字符串数组，则 `class` 将默认为 `property` 数组的第一个元素。
`css-var`	Optional	`false`	表示生成 CSS 变量还是 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 的哪些值。可以是列表或Map（在实用程序或 Sass 变量中设置）。

当 values 为列表时，例如 text-decoration 实用程序：

values: none underline line-through

当 values 为Map时，例如 opacity 实用程序：

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

当 values 为一个 Sass 变量，这个变量可以是列表或Map，如在我们的 position 实用程序中：

values: $position-values

Class

使用 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; }

CSS 变量实用程序

将 css-var 布尔选项设置为 true，API 将为给定的选择器生成本地 CSS 变量，而不是通常的 property: value 规则。例如我们的 .text-opacity-* 实用程序：

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

输出：

.text-opacity-25 { --bs-text-opacity: .25; }
.text-opacity-50 { --bs-text-opacity: .5; }
.text-opacity-75 { --bs-text-opacity: .75; }
.text-opacity-100 { --bs-text-opacity: 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

启用 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 的工作原理，请了解如何添加您自己的自定义类并修改我们的默认实用程序。

覆盖实用程序

使用相同的键覆盖现有实用程序。例如，如果您想要其他响应式 overflow 实用程序类，您可以这样做：

$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/utilities";

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

修改实用程序

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

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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%),
        ),
      ),
    ),
  )
);

启用响应式

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

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

现在，这将为每个断点生成 .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/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

删除实用程序

通过将组键设置为 null 来删除任何默认实用程序。例如，要删除我们所有的 width 实用程序，请创建一个 $utilities map-merge 并添加 "width": null内。

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

Remove utility in RTL

Some edge cases make RTL styling difficult, such as line breaks in Arabic. Thus utilities can be dropped from RTL output by setting the rtl option to false:

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

Output:

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

This doesn’t output anything in RTL, thanks to the RTLCSS remove control directive.