logoOutUI

⌘ K
  • 指南
  • 组件
  • 工具类
  • 其他
v5.3.x
  • API
  • Background
  • Border
  • Color
  • Display
  • Flex
  • Float
  • Interaction
  • Object Fit
  • Opacity
  • Overflow
  • Position
  • Shadow
  • Sizing
  • Spacing
  • Text
  • Vertical Align
  • Visibility
  • Z-Index
最后更新时间：
Background
Copyright © 2021-present 粤ICP备2021136339号
‌
‌
‌
‌

API

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

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

$utilities 映射包含我们的所有工具，稍后会与你的自定义 $utilities 映射（如果存在）合并。工具映射包含工具组的键控列表，这些工具组接受以下选项：

选项类型默认值描述
property必需–属性名称，可以是字符串或字符串数组（例如，水平填充或边距）。
values必需–值的列表，或者如果您不希望类名与值相同，则为映射。如果使用 null 作为映射键，则不会在类名前添加类名。
class可选null生成的类名。如果没有提供且属性是字符串数组，则默认为属性数组的第一个元素。如果没有提供且属性是字符串，则使用值的键作为类名。
css-var可选false布尔值，表示是否生成 CSS 变量而不是 CSS 规则。
css-variable-name可选null规则集内的自定义未加前缀的 CSS 变量名称。
local-vars可选null除了 CSS 规则之外要生成的本地 CSS 变量映射。
state可选null要生成的伪类变体列表（例如，:hover 或 :focus）。
responsive可选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 选项指定将在工具类的规则集中生成本地 CSS 变量的 Sass 映射。请注意，可能需要额外的工作才能在生成的 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";

删除工具

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

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

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

添加、删除、修改

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

@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 */

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