工具 API

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

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

🌐 Bootstrap utilities are generated with our utility API and can be used to modify or extend our default set of utility classes via Sass. Our utility API is based on a series of Sass maps and functions for generating families of classes with various options. If you’re unfamiliar with Sass maps, read up on the official Sass docs to get started.

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

🌐 The $utilities map contains all our utilities and is later merged with your custom $utilities map, if present. 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, `class` is not prepended to the class name.
`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. If not provided and `property` is a string, the `values` keys are used for the `class` names.
`css-var`	Optional	`false`	Boolean to generate CSS variables instead of CSS rules.
`css-variable-name`	Optional	null	Custom un-prefixed name for the CSS variable inside the ruleset.
`local-vars`	Optional	null	Map of local CSS variables to generate in addition to the CSS rules.
`state`	Optional	null	List of pseudo-class variants (e.g., `:hover` or `:focus`) to generate.
`responsive`	Optional	`false`	Boolean indicating if responsive classes should be generated.
`rfs`	Optional	`false`	Boolean to enable fluid rescaling with 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.

API 解释

🌐 API explained

所有实用程序变量都被添加到我们 _utilities.scss 样式表中的 $utilities 变量中。每组实用程序看起来像这样：

🌐 All utility variables are added to the $utilities variable within our _utilities.scss stylesheet. 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

任何实用工具都必须设置必需的 property 键，并且它必须包含一个有效的 CSS 属性。该属性用于生成的实用工具规则集中。当省略 class 键时，它也用作默认类名。考虑 text-decoration 实用工具：

🌐 The required property key must be set for any utility, and it must contain a valid CSS property. This property is used in the generated utility’s ruleset. When the class key is omitted, it also serves as the default class name. Consider the text-decoration utility:

$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

使用 values 键来指定在生成的类名和规则中应使用哪些 property 的值。可以是列表或映射（在工具中设置或在 Sass 变量中设置）。

🌐 Use the values key to specify which values for the specified property should be used in the generated class names and rules. Can be a list or map (set in the utilities or in a Sass variable).

作为列表，就像使用 text-decoration 工具一样：

🌐 As a list, like with text-decoration utilities:

values: none underline line-through

作为地图，就像使用 opacity 工具一样：

🌐 As a map, like with opacity utilities:

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

作为设置列表或映射的 Sass 变量，如我们在 position 工具中所示：

🌐 As a Sass variable that sets the list or map, as in our position utilities:

values: $position-values

类

🌐 Class

使用 class 选项来更改已编译 CSS 中使用的类前缀。例如，要将其从 .opacity-* 更改为 .o-*：

🌐 Use the class option to change the class prefix used in the compiled CSS. For example, to change from .opacity-* to .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; }

如果 class: null，为每个 values 键生成类：

🌐 If class: null, generates classes for each of the values keys:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

输出：

🌐 Output:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

CSS 变量工具

🌐 CSS variable utilities

将 css-var 布尔选项设置为 true，API 将为给定的选择器生成本地 CSS 变量，而不是通常的 property: value 规则。添加可选的 css-variable-name 以设置与类名不同的 CSS 变量名。

🌐 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. Add an optional css-variable-name to set a different CSS variable name than the class name.

考虑我们的 .text-opacity-* 工具。如果我们添加 css-variable-name 选项，就会得到一个自定义输出。

🌐 Consider our .text-opacity-* utilities. If we add the css-variable-name option, we'll get a custom output.

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

输出：

🌐 Output:

.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 CSS variables

使用 local-vars 选项来指定一个 Sass 映射，该映射将在实用程序类的规则集中生成本地 CSS 变量。请注意，在生成的 CSS 规则中使用这些本地 CSS 变量可能需要额外的工作。例如，考虑我们的 .bg-* 实用程序：

🌐 Use the local-vars option to specify a Sass map that will generate local CSS variables within the utility class’s ruleset. Please note that it may require additional work to consume those local CSS variables in the generated CSS rules. For example, consider our .bg-* utilities:

$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

使用 state 选项生成伪类变体。示例伪类有 :hover 和 :focus。当提供状态列表时，会为该伪类创建类名。例如，要在悬停时改变不透明度，添加 state: hover，你将在编译后的 CSS 中得到 .opacity-hover:hover。

🌐 Use the state option to generate pseudo-class variations. Example pseudo-classes are :hover and :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 focus。

🌐 Need multiple pseudo-classes? Use a space-separated list of states: 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

添加 responsive 布尔值以在所有断点上生成响应式工具（例如，.opacity-md-25）。

🌐 Add the responsive boolean to generate responsive utilities (e.g., .opacity-md-25) across all breakpoints.

$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

启用 print 选项还会生成用于打印的工具类，这些类仅在 @media print { ... } 媒体查询中应用。

🌐 Enabling the print option will also generate utility classes for print, which are only applied within the @media print { ... } media query.

$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

API生成的所有工具都包含!important，以确保它们按预期覆盖组件和修饰类。你可以通过$enable-important-utilities变量在全局切换此设置（默认为true）。

🌐 All utilities generated by the API include !important to ensure they override components and modifier classes as intended. You can toggle this setting globally with the $enable-important-utilities variable (defaults to true).

使用 API

🌐 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.

覆盖工具

🌐 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

新的工具可以通过 map-merge 添加到默认的 $utilities 映射中。确保首先导入我们所需的 Sass 文件和 _utilities.scss，然后使用 map-merge 添加额外的工具。例如，下面是如何添加一个具有三个值的响应式 cursor 工具。

🌐 New utilities can be added to the default $utilities map with a map-merge. Make sure our required Sass files and _utilities.scss are imported first, then use the map-merge to add your additional utilities. For example, here’s how to add a responsive cursor utility with three values.

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

修改工具

🌐 Modify utilities

使用 map-get 和 map-merge 函数修改默认 $utilities 地图中的现有实用程序。在下面的示例中，我们向 width 实用程序添加了一个额外的值。从初始 map-merge 开始，然后指定要修改的实用程序。接着，使用 map-get 获取嵌套的 "width" 地图，以访问并修改实用程序的选项和值。

🌐 Modify existing utilities in the default $utilities map with map-get and map-merge functions. In the example below, we’re adding an additional value to the width utilities. Start with an initial map-merge and then specify which utility you want to modify. From there, fetch the nested "width" map with map-get to access and modify the utility’s options and values.

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

启用响应式

🌐 Enable responsive

你可以为当前默认情况下不响应的现有工具集启用响应类。例如，要使 border 类具有响应性：

🌐 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:

@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 将如下所示：

🌐 This will now generate responsive variations of .border and .border-0 for each breakpoint. Your generated CSS will look like this:

.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

缺少 v4 工具，或者习惯使用另一种命名约定？工具 API 可用于覆盖给定工具生成的 class——例如，将 .ms-* 工具重命名为旧式的 .ml-*：

🌐 Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting class of a given utility—for example, to rename .ms-* utilities to oldish .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";

删除工具

🌐 Remove utilities

使用 map-remove() Sass 函数移除任何默认实用工具。

🌐 Remove any of the default utilities with the map-remove() Sass function.

@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 来移除该工具。

🌐 You can also use the map-merge() Sass function and set the group key to null to remove the utility.

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

添加、删除、修改

🌐 Add, remove, modify

你可以使用 map-merge() Sass 函数一次性添加、删除和修改许多实用工具。以下是如何将之前的示例合并为一个更大的映射的方法。

🌐 You can add, remove, and modify many utilities all at once with the map-merge() Sass function. Here’s how you can combine the previous examples into one larger 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 中的工具

🌐 Remove utility in RTL

一些边缘情况会使 RTL 样式变得困难，例如阿拉伯语中的换行。因此可以通过将 rtl 选项设置为 false 来从 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 */

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

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