Skip to main content Skip to docs navigation
View on GitHub

Utility API实用程序API

The utility API is a Sass-based tool to generate utility classes.实用程序API是一个基于Sass的工具，用于生成实用程序类。

On this page本页内容

Bootstrap utilities are generated with our utility API and can be used to modify or extend our default set of utility classes via Sass. Bootstrap实用程序是使用我们的实用程序API生成的，可用于通过Sass修改或扩展我们的默认实用程序类集。Our utility API is based on a series of Sass maps and functions for generating families of classes with various options. 我们的实用程序API基于一系列Sass映射和函数，用于生成具有各种选项的类族。If you’re unfamiliar with Sass maps, read up on the official Sass docs to get started.如果您不熟悉Sass地图，请阅读官方Sass文档以开始。

The $utilities map contains all our utilities and is later merged with your custom $utilities map, if present. $utilities映射包含我们的所有实用程序，稍后将与您的自定义$utilities映射（如果存在）合并。The utility map contains a keyed list of utility groups which accept the following options:公用设施图包含公用设施组的键控列表，这些公用设施组接受以下选项：

Option选项 Type类型 Default value默认值 Description描述
property Required – Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins).属性名称，可以是字符串或字符串数组（例如，水平填充或边距）。
values Required – List of values, or a map if you don’t want the class name to be the same as the value. 值列表，或者如果不希望类名与值相同，则使用映射。If null is used as map key, it isn’t compiled.如果将null用作映射键，则不会编译它。
class Optional null Name of the generated class. 生成的类的名称。If not provided and property is an array of strings, class will default to the first element of the property array.如果未提供，并且property是字符串数组，则class将默认为属性数组的第一个元素。
css-var Optional false Boolean to generate CSS variables instead of CSS rules.布尔值生成CSS变量，而不是CSS规则。
local-vars Optional null Map of local CSS variables to generate in addition to the CSS rules.除CSS规则外，要生成的本地CSS变量的映射。
state Optional null List of pseudo-class variants (e.g., :hover or :focus) to generate.要生成的伪类变体列表（例如:hover或:focus）。
responsive Optional false Boolean indicating if responsive classes should be generated.指示是否应生成响应类的布尔值。
rfs Optional false Boolean to enable fluid rescaling with RFS.布尔值以启用使用RFS的流体重缩放。
print Optional false Boolean indicating if print classes need to be generated.指示是否需要生成打印类的布尔值。
rtl Optional true Boolean indicating if utility should be kept in RTL.指示实用程序是否应保留在RTL中的布尔值。

API explainedAPI解释

All utility variables are added to the $utilities variable within our _utilities.scss stylesheet. 所有实用程序变量都添加到_utilities.scss样式表中的$utilities变量中。Each group of utilities looks something like this:每个实用程序组的外观如下所示：

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

Which outputs the following:其输出如下：

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

Property属性

The required property key must be set for any utility, and it must contain a valid CSS property. 必须为任何实用程序设置所需的property键，并且它必须包含有效的CSS属性。This property is used in the generated utility’s ruleset. 此属性在生成的实用程序的规则集中使用。When the class key is omitted, it also serves as the default class name. 省略class键时，它也将用作默认类名。Consider the text-decoration utility:考虑text-decoration实用程序：

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

Output:输出：

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

Values值

Use the values key to specify which values for the specified property should be used in the generated class names and rules. 使用values键指定在生成的类名和规则中应使用指定property的哪些值。Can be a list or map (set in the utilities or in a Sass variable).可以是列表或映射（在实用程序或Sass变量中设置）。

As a list, like with text-decoration utilities:作为列表，与text-decoration实用程序类似：

values: none underline line-through

As a map, like with opacity utilities:作为贴图，与opacity实用程序类似：

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

As a Sass variable that sets the list or map, as in our position utilities:作为设置列表或映射的Sass变量，如在我们的position实用程序中：

values: $position-values

Class类

Use the class option to change the class prefix used in the compiled CSS. 使用class选项更改已编译CSS中使用的类前缀。For example, to change from .opacity-* to .o-*:例如，要从.opacity-*更改为.o-*：

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

Output:输出：

.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 variable utilitiesCSS变量实用程序

Set the css-var boolean option to true and the API will generate local CSS variables for the given selector instead of the usual property: value rules. 将css-var布尔选项设置为true，API将为给定的选择器生成本地css变量，而不是通常的property: value规则。Consider our .text-opacity-* utilities:考虑我们的.text-opacity-*实用程序：

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

Output:输出：

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

Local CSS variables局部CSS变量

Use the local-vars option to specify a Sass map that will generate local CSS variables within the utility class’s ruleset. 使用local-vars选项指定Sass映射，该映射将在实用程序类的规则集中生成本地CSS变量。Please note that it may require additional work to consume those local CSS variables in the generated CSS rules. 请注意，在生成的CSS规则中使用这些本地CSS变量可能需要额外的工作。For example, consider our .bg-* utilities:例如，考虑我们的.bg-*实用工具：

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

Output:输出：

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

States状态

Use the state option to generate pseudo-class variations. 使用state选项生成伪类变体。Example pseudo-classes are :hover and :focus. 示例伪类有:hover和:focus。When a list of states are provided, classnames are created for that pseudo-class. 当提供状态列表时，将为该伪类创建类名。For example, to change opacity on hover, add state: hover and you’ll get .opacity-hover:hover in your compiled CSS.例如，若要更改悬停时的不透明度，请添加state:hover，您将在编译的CSS中获得.opacity-hover:hover。

Need multiple pseudo-classes? Use a space-separated list of states: state: hover focus.需要多个伪类吗？使用空格分隔的状态列表：state: hover focus。

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

Output:输出：

.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响应式的

Add the responsive boolean to generate responsive utilities (e.g., .opacity-md-25) across all breakpoints.添加responsive布尔值以跨所有断点生成响应实用程序（例如，opacity-md-25）。

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

Output:输出：

.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印刷品

Enabling the print option will also generate utility classes for print, which are only applied within the @media print { ... } media query.启用print选项还将生成打印实用程序类，这些实用程序类仅在@media print { ... }媒体查询中应用。

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

Output:输出：

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

Importance重要性

All utilities generated by the API include !important to ensure they override components and modifier classes as intended. API生成的所有实用程序包括括！重要的是确保它们按预期重写组件和修改器类。You can toggle this setting globally with the $enable-important-utilities variable (defaults to true).您可以使用$enable-important-utilities变量（默认为true）全局切换此设置。

Using the API使用API

Now that you’re familiar with how the utilities API works, learn how to add your own custom classes and modify our default utilities.现在您已经熟悉了实用程序API的工作原理，了解如何添加您自己的自定义类并修改我们的默认实用程序。

Override utilities覆盖实用程序

Override existing utilities by using the same key. 使用相同的键覆盖现有的实用程序。For example, if you want additional responsive overflow utility classes, you can do this:例如，如果需要其他响应溢出实用程序类，可以执行以下操作：

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

Add utilities添加实用程序

New utilities can be added to the default $utilities map with a map-merge. 可以通过map-merge将新的实用程序添加到默认的$utilities映射中。Make sure our required Sass files and _utilities.scss are imported first, then use the map-merge to add your additional utilities. 确保首先导入我们所需的Sass文件和_utilities.scss，然后使用map-merge添加其他实用程序。For example, here’s how to add a responsive cursor utility with three values.例如，下面介绍如何添加具有三个值的响应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,
)
)
);

Modify utilities修改实用程序

Modify existing utilities in the default $utilities map with map-get and map-merge functions. 使用map-get和map-merge函数修改默认$utilities映射中的现有实用程序。In the example below, we’re adding an additional value to the width utilities. 在下面的示例中，我们向width实用程序添加了一个附加值。Start with an initial map-merge and then specify which utility you want to modify. 从初始map-merge开始，然后指定要修改的实用程序。From there, fetch the nested "width" map with map-get to access and modify the utility’s options and values.从那里，利用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%),
),
),
),
)
);

Enable responsive启用响应性

You can enable responsive classes for an existing set of utilities that are not currently responsive by default. 您可以为默认情况下当前没有响应的现有实用程序集启用响应类。For example, to make the border classes responsive:例如，要使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 ),
),
)
);

This will now generate responsive variations of .border and .border-0 for each breakpoint. 现在，这将为每个断点生成.border和.border-0的响应变体。Your generated CSS will look like this:生成的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 { ... }
}

Rename utilities重命名实用程序

Missing v4 utilities, or used to another naming convention? 缺少v4实用程序，或使用了其他命名约定？The utilities API can be used to override the resulting class of a given utility—for example, to rename .ms-* utilities to oldish .ml-*:实用程序API可用于覆盖给定实用程序的结果类，例如，将.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 ),
),
)
);

Remove utilities删除实用程序

Remove any of the default utilities by setting the group key to null. 通过将组键设置为null，删除任何默认实用程序。For example, to remove all our width utilities, create a $utilities map-merge and add "width": null within.例如，要删除所有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删除RTL中的实用程序

Some edge cases make RTL styling difficult, such as line breaks in Arabic. 某些边缘情况使RTL样式设置困难，例如阿拉伯语中的换行符。Thus utilities can be dropped from RTL output by setting the rtl option to false:因此，通过将RTL选项设置为false，可以从RTL输出中删除实用程序：

$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.由于RTLCSS remove control指令，这不会在RTL中输出任何内容。