ユーティリティAPI

Utility API

ユーティリティAPIは、Sassベースのユーティリティクラスを生成します。

項目

ユーティリティクラスは、値を変更・拡張できるユーティリティAPIで生成されます。Sassマップに慣れていない場合は、公式ドキュメントを参照してください。

マップは、すべてのユーティリティを含んでいて、カスタム(もしあれば)の$utilitiesマップとマージされます。ユーティリティマップには、以下のオプションを受け入れるユーティリティグループのキー付きリストが含まれています。

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`	印刷クラスを生成する必要があるかどうかを示すブール値。
`rtl`	Optional	`true`	ユーティリティをRTLで保持するかどうかを示すブール値。

APIについて

すべてのユーティリティは$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,
)

positionユーティリティのように、リストまたはマップを設定するSass変数として以下のものがあります。:

values: $position-values

クラス

コンパイルされたCSSで使用されるクラスの接頭辞を変更するにはclassオプションを使用します。例えば、.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オプション(Boolean)をtrueに設定すると、通常のproperty: valueルールの代わりに、APIが指定されたセレクタに対してローカル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
    )
  ),
);

出力:

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

出力:

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

レスポンシブ

すべてのブレイクポイントでレスポンシブユーティリティ(例: .opacity-md-25)を生成するためにresponsiveオプション(Boolean)を追加します。

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

Importance

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を使用してユーティリティを追加します。たとえば、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から始めて、変更するユーティリティを指定します。そこからネストされた"width"マップをmap-getでフェッチして、ユーティリティのオプションと値にアクセスして変更します。

@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関数を使えば、多くのユーティリティを一度に追加、削除、変更することができます。先ほどの例を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 stylingが困難です。したがって、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 */

The RTLCSS remove control directiveにより、これはRTLに何も出力しません。