實用程式 API

實用程式 API 是基於 Sass 的工具，用於產生實用程式類別。

在此頁面上

Bootstrap 實用程式使用我們的實用程式 API 產生，並可透過 Sass 修改或延伸我們預設的實用程式類別。我們的實用程式 API 基於一系列 Sass 對應與函式，用於產生具有各種選項的類別系列。如果您不熟悉 Sass 對應，請閱讀官方 Sass 文件以開始使用。

$utilities 地圖包含我們所有的工具，稍後會與您自訂的 $utilities 地圖合併（如果存在）。工具地圖包含一個工具群組的鍵控清單，接受下列選項

選項	類型	預設值	說明
`屬性`	必要	–	屬性的名稱，可以是字串或字串陣列（例如，水平內距或外距）。
`值`	必要	–	值清單，或地圖（如果您不希望類別名稱與值相同）。如果 `null` 用作地圖鍵，`class` 就不會加到類別名稱之前。
`類別`	選用	null	產生類別的名稱。如果未提供，且 `屬性` 是字串陣列，`類別` 會預設為 `屬性` 陣列的第一個元素。如果未提供，且 `屬性` 是字串，`值` 鍵會用於 `類別` 名稱。
`css-var`	選用	`false`	布林值，用於產生 CSS 變數，而不是 CSS 規則。
`css-variable-name`	選用	null	規則集內 CSS 變數的自訂非前綴名稱。
`local-vars`	選用	null	除了 CSS 規則之外，要產生的本地 CSS 變數地圖。
`狀態`	選用	null	要產生的偽類別變異清單（例如，`:hover` 或 `:focus`）。
`回應式`	選用	`false`	布林值，表示是否應產生回應式類別。
`rfs`	選用	`false`	布林值，用於啟用 RFS 的流體重新縮放。
`列印`	選用	`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 選項來指定一個 Sass 地圖，它將在實用程式類別的規則集中產生本機 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;
}

狀態

使用 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 */

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