ユーティリティAPI Utility API

utility API は、ユーティリティクラスを生成するための Sass ベースのツールです。

On this page

Bootstrap ユーティリティは utility API で生成され、Sass を介してデフォルトのユーティリティクラスのセットを変更または拡張するために使用できます。utility API は、さまざまなオプションを持つクラスのファミリーを生成するための一連の Sass マップと関数に基づいています。Sass マップに不慣れな場合は、公式 Sass ドキュメントを読んで始めてください。

$utilities マップにはすべてのユーティリティが含まれており、存在する場合はカスタムの $utilities マップと後でマージされます。utility マップには、次のオプションを受け入れるユーティリティグループのキー付きリストが含まれています：

Option	Type	Default value	Description
`property`	Required	–	プロパティの名前。これは文字列または文字列の配列（例：水平方向のパディングやマージン）にできます。
`values`	Required	–	値のリスト、またはクラス名を値と同じにしたくない場合はマップ。マップキーとして `null` を使用すると、クラス名に `class` が先頭に追加されません。
`class`	Optional	null	生成されるクラスの名前。提供されず、`property` が文字列の配列の場合、`class` は `property` 配列の最初の要素がデフォルトになります。提供されず、`property` が文字列の場合、`values` キーが `class` 名に使用されます。
`css-var`	Optional	`false`	CSS ルールの代わりに CSS 変数を生成するかどうかのブール値。
`css-variable-name`	Optional	null	ルールセット内の CSS 変数のカスタムの接頭辞なし名。
`local-vars`	Optional	null	CSS ルールに加えて生成するローカル CSS 変数のマップ。
`state`	Optional	null	生成する疑似クラスバリアント（例：`:hover` または `:focus`）のリスト。
`responsive`	Optional	`false`	レスポンシブクラスを生成するかどうかを示すブール値。
`rfs`	Optional	`false`	RFS による流動的な再スケーリングを有効にするブール値。
`print`	Optional	`false`	print クラスを生成する必要があるかどうかを示すブール値。
`rtl`	Optional	`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
  )
);

Output:

.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 に対してどの値を生成されたクラス名とルールで使用するかを指定します。リストまたはマップ（utilities または 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,
    )
  )
);

Output:

.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 は通常の property: value ルールの代わりに、指定されたセレクタのローカル CSS 変数を生成します。オプションで 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
    )
  ),
);

Output:

.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 オプションを使用して、ユーティリティクラスのルールセット内でローカル CSS 変数を生成する Sass マップを指定します。生成された CSS ルールでこれらのローカル CSS 変数を使用するには、追加の作業が必要になる場合があることに注意してください。たとえば、.bg-* ユーティリティを考えてみましょう：

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

Output:

.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,
    )
  )
);

Output:

.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,
    )
  )
);

Output:

.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 { ... } メディアクエリ内でのみ適用される print 用のユーティリティクラスも同様に生成されます。

$utilities: (
  "opacity": (
    property: opacity,
    print: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Output:

.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の使用

utilities API の仕組みに慣れたので、独自のカスタムクラスを追加し、デフォルトのユーティリティを変更する方法を学びましょう。

ユーティリティをオーバーライド

同じキーを使用して既存のユーティリティをオーバーライドします。たとえば、追加のレスポンシブ overflow ユーティリティクラスが必要な場合は、次のようにできます：

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

ユーティリティを追加

新しいユーティリティは、map-merge を使用してデフォルトの $utilities マップに追加できます。必要な Sass ファイルと _utilities.scss を最初にインポートし、次に map-merge を使用して追加のユーティリティを追加します。たとえば、3 つの値を持つレスポンシブな 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 のユーティリティがないか、別の命名規則に慣れていますか？utilities 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 関数を使用して、多数のユーティリティを一度に追加、削除、変更できます。以前の例を 1 つの大きなマップに組み合わせる方法は次のとおりです。

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

Output:

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

RTLCSS の remove 制御ディレクティブのおかげで、RTL では何も出力されません。