유틸리티 API

유틸리티 API는 유틸리티 클래스를 생성하는 Sass 기반 도구입니다.

이 페이지에서

부트스트랩 유틸리티는 유틸리티 API로 생성되며 Sass를 통해 기본 유틸리티 클래스 세트를 수정하거나 확장하는 데 사용할 수 있습니다. 유틸리티 API는 다양한 옵션이 있는 클래스 패밀리를 생성하기 위한 일련의 Sass 맵 및 함수를 기반으로 합니다. Sass 맵에 익숙하지 않다면 공식 Sass 문서 를 읽어보고 시작하십시오.

지도에는 모든 유틸리티 가 포함되어 있으며 나중에 사용자 정의 지도(있는 경우) $utilities와 병합됩니다 . $utilities유틸리티 맵에는 다음 옵션을 허용하는 유틸리티 그룹의 키 목록이 포함되어 있습니다.

옵션	유형	기본값	설명
`property`	필수의	–	속성의 이름으로, 문자열 또는 문자열 배열(예: 수평 패딩 또는 여백)이 될 수 있습니다.
`values`	필수의	–	값 목록 또는 클래스 이름이 값과 동일하지 않게 하려는 경우에는 맵입니다. `null`맵 키로 사용되는 경우 `class`클래스 이름 앞에 추가되지 않습니다.
`class`	선택 과목	없는	생성된 클래스의 이름입니다. 제공되지 않고 `property`문자열 배열인 `class`경우 기본적으로 배열의 첫 번째 요소가 사용 `property`됩니다. 제공되지 않고 `property`문자열이면 `values`키가 `class`이름에 사용됩니다.
`css-var`	선택 과목	`false`	CSS 규칙 대신 CSS 변수를 생성하는 부울입니다.
`css-variable-name`	선택 과목	없는	규칙 세트 내부의 CSS 변수에 대한 접두사가 붙지 않은 사용자 정의 이름입니다.
`local-vars`	선택 과목	없는	CSS 규칙 외에 생성할 로컬 CSS 변수의 맵입니다.
`state`	선택 과목	없는	생성할 의사 클래스 변형 목록(예: `:hover`또는 `:focus`)입니다.
`responsive`	선택 과목	`false`	반응형 클래스를 생성해야 하는지 여부를 나타내는 부울입니다.
`rfs`	선택 과목	`false`	RFS로 유체 재조정 을 가능하게 하는 부울 .
`print`	선택 과목	`false`	인쇄 클래스를 생성해야 하는지 여부를 나타내는 부울입니다.
`rtl`	선택 과목	`true`	유틸리티를 RTL에 유지해야 하는지 여부를 나타내는 부울입니다.

API 설명

모든 유틸리티 변수는 스타일시트 $utilities내의 변수에 추가됩니다 _utilities.scss. 각 유틸리티 그룹은 다음과 같습니다.

$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

수업

이 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부울 옵션을 로 설정 하면 API가 일반적인 규칙 true대신 지정된 선택기에 대한 로컬 CSS 변수를 생성합니다 . 클래스 이름과 다른 CSS 변수 이름을 설정 property: value하려면 옵셔널을 추가하세요 .css-variable-name

.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하면 .opacity-hover:hover컴파일된 CSS가 표시됩니다.

여러 의사 클래스가 필요하십니까? 공백으로 구분된 상태 목록을 사용하십시오 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,
  ),
);

유틸리티 추가

$utilities를 사용하여 기본 맵에 새 유틸리티를 추가할 수 있습니다 map-merge. 필요한 Sass 파일과 _utilities.scss가져오기를 먼저 확인한 다음 를 사용 map-merge하여 추가 유틸리티를 추가하십시오. cursor예를 들어, 다음 은 3개의 값으로 반응형 유틸리티 를 추가하는 방법 입니다.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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";

유틸리티 수정

및 기능 을 사용하여 기본 $utilities맵 에서 기존 유틸리티를 수정 합니다. 아래 예에서는 유틸리티에 추가 값을 추가하고 있습니다. 이니셜 로 시작한 다음 수정할 유틸리티를 지정하십시오. 거기에서 중첩 맵을 가져와 유틸리티의 옵션과 값에 액세스하고 수정합니다.map-getmap-mergewidthmap-merge"width"map-get

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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/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-*유틸리티 이름을 oldish 로 변경할 수 있습니다 .ml-*.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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/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/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/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 */

이것은 RTLCSS remove제어 지시어 덕분에 RTL에서 아무 것도 출력하지 않습니다 .