通用類別 API（Utility API）

通用類別 API 是一個基於 Sass 的工具，用於產生通用類別。

本頁內容

Bootstrap 工具程式是透過我們的通用類別 API 產生的，可用於透過 Sass 修改或擴充我們預設的通用類別集合。我們的通用類別 API 基於一系列 Sass maps 和函式，用於產生具有各種選項的類別族群。如果您不熟悉 Sass maps，請先閱讀 Sass 官方文件以開始使用。

$utilities map 包含我們所有的工具程式，並會在稍後與您自訂的 $utilities map 合併（如果有的話）。utility map 包含一個以鍵值組成的工具群組清單，接受以下選項：

選項	類型	預設值	說明
`property`	必填	–	屬性名稱，可以是字串或字串陣列（例如水平 padding 或 margin）。
`values`	必填	–	值的清單，或是當您不希望類別名稱與值相同時使用的 map。如果使用 `null` 作為 map 鍵，則 `class` 不會被加到類別名稱前面。
`class`	選填	null	產生的類別名稱。如果未提供且 `property` 是字串陣列，`class` 將預設為 `property` 陣列的第一個元素。如果未提供且 `property` 是字串，則使用 `values` 的鍵作為 `class` 名稱。
`css-var`	選填	`false`	布林值，用於產生 CSS 變數而非 CSS 規則。
`css-variable-name`	選填	null	規則集內 CSS 變數的自訂無前綴名稱。
`local-vars`	選填	null	除了 CSS 規則外，額外產生的區域 CSS 變數 map。
`state`	選填	null	要產生的偽類別變體清單（例如 `:hover` 或 `:focus`）。
`responsive`	選填	`false`	布林值，指示是否應產生響應式類別。
`rfs`	選填	`false`	布林值，啟用 RFS 流體縮放。
`print`	選填	`false`	布林值，指示是否需要產生列印類別。
`rtl`	選填	`true`	布林值，指示工具程式是否應保留在 RTL 中。

API 說明（API explained）

所有工具變數都會在我們的 _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

任何工具程式都必須設定必填的 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

使用 values 鍵來指定指定 property 應使用哪些值來產生類別名稱和規則。可以是清單或 map（在工具程式中或在 Sass 變數中設定）。

作為清單，如同 text-decoration 工具程式：

values: none underline line-through

作為 map，如同 opacity 工具程式：

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

作為設定清單或 map 的 Sass 變數，如同我們的 position 工具程式：

values: $position-values

Class

使用 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 variable utilities）

將 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 CSS variables）

使用 local-vars 選項來指定一個 Sass map，它將在通用類別的規則集中產生區域 CSS 變數。請注意，在產生的 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;
}

States

使用 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）

加入 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）

啟用 print 選項也會產生列印用的通用類別，這些類別僅在 @media print { ... } media query 中套用。

$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; }
}

重要性（Importance）

所有由 API 產生的工具程式都包含 !important，以確保它們能如預期般覆寫元件和修飾類別。您可以使用 $enable-important-utilities 變數全域切換此設定（預設為 true）。

使用 API（Using the API）

現在您已熟悉通用類別 API 的運作方式，請了解如何加入您自己的自訂類別並修改我們的預設工具程式。

覆寫通用類別（Override utilities）

使用相同的鍵來覆寫現有工具程式。例如，如果您想要額外的響應式 overflow 通用類別，您可以這樣做：

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

新增通用類別（Add utilities）

可以使用 map-merge 將新工具程式加入到預設的 $utilities map 中。請確保先匯入我們必要的 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";

修改通用類別（Modify utilities）

使用 map-get 和 map-merge 函式修改預設 $utilities map 中的現有工具程式。在下面的範例中，我們為 width 工具程式加入一個額外的值。從初始的 map-merge 開始，然後指定您要修改的工具程式。從那裡，使用 map-get 取得巢狀的 "width" 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,
  (
    "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 類別變成響應式：

@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 { ... }
}

重新命名通用類別（Rename utilities）

想念 v4 的工具程式，或習慣使用其他命名慣例？Utility 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";

移除通用類別（Remove utilities）

使用 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";

新增、移除、修改（Add, remove, modify）

您可以使用 map-merge() Sass 函式一次新增、移除和修改許多工具程式。以下是如何將前面的範例組合成一個更大的 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 輸出中排除：

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

這在 RTL 中不會輸出任何內容，這要感謝 RTLCSS remove 控制指令。