View on GitHub

API

通用類別 API 是基於 Sass 工具所產生的通用類別 class。

On this page

Bootstrap 通用類別是使用我們的通用類 API 所生成的，並可以通過 Sass 修改或擴充我們預設的通用類別。我們的通用類 API 是基於一系列用於產生帶有各種選項之類別的 Sass maps 及函式。如果你不熟悉 Sass maps，閱讀 Sass 官方文檔並開始使用。

$utilities map 包含我們所有的通用類別，並在之後與您自訂的 $utilities map 合併 (如果有的話)。utility map 包含了通用類群組的鍵值清單，這些清單接受以下選項：

選項	類型	介紹
`property`	必要	屬性的名稱，可以是字串或是字串陣列 ( 例如，水平的 padding 或 margin )。
`values`	必要	清單中的值或 map，在您不希望 class 名稱與值相同時使用。如果將 `null` 作為 map 鍵值，則不會編譯它。
`class`	可選	當您不希望 class 名稱與屬性相同時所使用的變數。如果您不提供 `class` 鍵值，且 `property` 鍵值是字串陣列，則 class 名稱將是 `property` 陣列的第一個元素。
`state`	可選	為通用類別生成的虛擬類別類清單，像是 `:hover` 或 `:focus`。沒有預設值。
`responsive`	可選	用於指示是否要生成響應式類別的布林值。預設值為 `false`。
`rfs`	可選	用於啟用流體縮放的布林值。可以查看 RFS 頁面以了解如何運作。預設值為 `false`。
`print`	可選	用於指示是否要生成 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 中所使用的 class 前綴：

$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。提供狀態列表後，將為虛擬類別創建類名。例如，要更改 hover 時的透明度，請添加 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; }
.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; }
}

更改通用類別

透過使用相同的鍵值來覆蓋現有的通用類別。例如，您需要加入響應式 overflow 通用類別的話，你可以這樣做：

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

通用類別 Print

啟用 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 map。首先確定有導入您的 _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 map 中預設的通用類別。在下面的範例中，我們在通用類別 width 加入了一個附加值。從建立一個初始的 map-merge 開始，然後指定要修改的通用類別。在那裡使用 map-get fetch 一個巢狀的 width map，以訪問和修改通用類別的選項和值。

@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%),
        ),
      ),
    ),
  )
);

Rename utilities

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/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
  )
);

在 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 中它不會輸出任何內容。