API
通用類別 API 是基於 Sass 工具所產生的通用類別 class。
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。首先確定有導入所需的 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-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%),
),
),
),
)
);
重新命名通用類別
缺少 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 中它不會輸出任何內容。