API

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

本页导航↓

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

$utilities 映射包含我们所有的实用工具，稍后将与您的自定义 $utilities 映射合并(如果存在的话)。实用工具映射包含一个实用工具组的键控列表，它接受以下选项:

选项	类型	描述
`property`	必需	属性的名称，它可以是一个字符串或字符串数组(例如，paddings或margins)。/td>
`values`	必需	值的列表，如果您不希望类名与值相同，则可以使用映射。如果使用 `null` 作为映射键，则不会编译它。
`class`	可选	变量作为类名，如果您不想让它与属性相同。如果您没有提供 `class` ，而 `property` 键是一个字符串数组，则类名将是 `property` 数组的第一个元素。
`state`	可选	要为实用工具生成的伪类变体列表，如 `:hover` 或 `:focus` 。没有默认值。
`responsive`	可选	指示是否需要生成响应类的布尔值。默认为 `false` 。
`rfs`	可选	布尔值以启用流动重缩放。请看RFS页面。默认为 `false` 。
`print`	可选	指示是否需要生成打印类的布尔值。默认为`false`。
`rtl`	可选	布尔值，指示实用工具是否应保留在RTL中。默认为 `true`。

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

自定义类的前缀

使用 class选项更改在编译后的CSS中使用的类前缀:

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

输出:

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

状态

使用 state 选项来生成伪类变体。伪类的例子有 :hover 和 :focus。当提供了一组状态时，就会为这个伪类创建类名。例如，要改变鼠标悬停的不透明度，添加 state: hover，你会得到. .opacity-hover:hover 在你编译的CSS中。

需要多个伪类?使用空格分隔的状态列表： 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; }
.opacity-25-hover:hover { opacity: .25; }
.opacity-50-hover:hover { opacity: .5; }
.opacity-75-hover:hover { opacity: .75; }
.opacity-100-hover:hover { opacity: 1; }

响应式工具

添加 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; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

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

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

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

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

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

改变工具

使用相同的键覆盖现有的实用工具。例如，如果你想要额外的响应式溢出实用工具类，你可以这样做:

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

打印工具

启用 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; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

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

使用API

现在您已经熟悉了实用工具API的工作方式，接下来学习如何添加您自己的自定义类和修改我们的默认实用工具。

添加工具

可以使用 map-merge 将新的实用工具添加到默认的 $utilities 映射。确保我们的 _utilities.scss 首先导入，然后使用 map-merge 添加其他实用工具。例如，下面是如何添加一个具有三个值的响应 cursor 实用工具。

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

$utilities: map-merge(
$utilities,
(
"width": map-merge(
  map-get($utilities, "width"),
  (
    values: map-merge(
      map-get(map-get($utilities, "width"), "values"),
      (10: 10%),
    ),
  ),
),
)
);

删除工具

通过将组键设置为 null 来删除任何缺省实用工具。例如，要删除所有的 width 工具，创建一个 $utilities map-merge ，并在其中添加 "width": null 。

@import "bootstrap/scss/utilities";

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

删除RTL中的工具

一些极端情况会使RTL样式变化变得困难，比如Arabic的换行符。因此，可以通过将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中不会输出任何东西。