Skip to main content Skip to docs navigation

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

六角學院的 Bootstrap 5 課程上線囉,立即與萬人一同學習最專業、最深入的 Bootstrap 5 課程。

立即上課去

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 生成通用類別,並僅能應用在 @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。首先確定有導入所需的 Sass 文件和 _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-getmap-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%),
        ),
      ),
    ),
  )
);

重新命名通用類別

缺少 v4 通用類別,還是習慣了另一種命名方式?通用類別 API 可用於覆蓋給定通用類別的 class—例如,將 .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

透過將群組鍵值設置為 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 中它不會輸出任何內容。