Utility API (ユーティリティAPI)

utility API は、Sassベースの utilityクラスを生成します。

On this page

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

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

Option	Type	Description
`property`	Required	これは文字列でも文字列の配列でも構いません (水平方向のパディングや余白などに必要です)。
`values`	Required	値のリスト、またはクラス名を値と同じにしたくない場合はマップ。 `null`がマップキーとして使用されている場合、コンパイルされません。
`class`	Optional	クラス名をプロパティと同じにしたくない場合に、クラス名を変更するための変数です。 `class`キーを指定せず、 `property`キーが文字列の配列である場合、クラス名は `property`配列の最初の要素になります。
`state`	Optional	utility 用に生成する `：hover`や`：focus`などの疑似クラスバリアントのリストです。デフォルト値はありません。
`responsive`	Optional	レスポンシブクラスを生成する必要があるかどうかを示す Boolean。デフォルトは `false`です。
`rfs`	Optional	再スケーリングを有効にする Boolean。これがどのように動作するかについては、 RFS のページを参照してください。デフォルトでは `false` です。
`print`	Optional	印刷クラスを生成する必要があるかどうかを示すブール値。デフォルトでは `false` です。
`rtl`	Optional	ユーティリティをRTLに保持する必要があるかどうかを示す Boolean。。デフォルトでは `true` です。

API explained

すべてのユーティリティは $utilities 変数に追加されます。カスタムユーティリティグループは以下のように追加することができます。

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

Which outputs the following:

.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

Custom class prefix

コンパイルされたCSSで使用される class prefix を変更するには、 classオプションを使用します。

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

Output:

.o-0 { opacity: 0; }
.o-25 { opacity: .25; }
.o-50 { opacity: .5; }
.o-75 { opacity: .75; }
.o-100 { opacity: 1; }

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

Output:

.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 utilities

responsive オプションを使うと、レスポンシブなユーティリティクラスを生成することができます。 (例えば .opacity-md-25 all breakpoints) 同じキーを使用することで、既存の utilities を上書きできます。例えば、よりレスポンシブで overflow utility の場合は、以下のようになります。 utility classes を使用すると、このようなことができます。

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

Output:

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

Changing utilities

同じキーを使用することで、既存の utilities を上書きできます。例えば、よりレスポンシブで overflow utility の場合は、以下のようになります。 utility classes を使用すると、このようなことができます。

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

Print utilities

printオプションを有効にすると、印刷用の utility classes も生成されます。これは、@media print {...}メディアクエリ内でのみ適用されます。

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

Output:

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

Using the API

独自のカスタムクラスを追加し、デフォルトの utilities を変更する方法です。

Add utilities

新しいユーティリティは、 map-mergeを使用してデフォルトの $ utilitiesマップに追加できます。必要なSassファイルと _utilities.scssが最初にインポートされていることを確認してから、 map-mergeを使用してユーティリティを追加します。たとえば、3つの値を持つレスポンシブな 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,
    )
  )
);

Modify utilities

map-get 関数と map-merge 関数を使用して, デフォルトの $utilities マップの既存の utilities を変更します。以下の例では, width utilities に値を追加しています。最初の map-merge から始めて、変更する utilities を指定します。そこから、ネストされた "width" マップを map-get でフェッチして、utilities のオプションと値にアクセスして変更します。

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

Rename utilities

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に設定して、デフォルトの utilities をすべて削除します。たとえば、すべての width utilities を削除するには、$utilities map-merge を作成し、その中に "width"：nullを追加します。

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

Remove utility in RTL

アラビア語の改行など一部のエッジケースでは, RTL styling が困難です。したがって, 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 */

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