Перайсці да асноўнага зместу Перайсці да навігацыі па дакументах
in English

Утыліта API

API утыліт - гэта інструмент на аснове Sass для стварэння класаў утыліт.

Утыліты Bootstrap ствараюцца з дапамогай нашага API утыліт і могуць выкарыстоўвацца для змены або пашырэння нашага стандартнага набору класаў утыліт праз Sass. Наша ўтыліта API заснавана на серыі карт і функцый Sass для стварэння сямействаў класаў з рознымі параметрамі. Калі вы не знаёмыя з картамі Sass, прачытайце афіцыйную дакументацыю Sass , каб пачаць.

Карта $utilitiesзмяшчае ўсе нашы ўтыліты і пазней аб'ядноўваецца з вашай карыстальніцкай $utilitiesкартай, калі яна ёсць. Карта камунальных службаў утрымлівае ключавы спіс груп камунальных паслуг, якія прымаюць наступныя параметры:

Варыянт Тып Значэнне па змаўчанні Апісанне
property абавязковы Імя ўласцівасці, гэта можа быць радок або масіў радкоў (напрыклад, гарызантальныя запаўненні або палі).
values абавязковы Спіс значэнняў або карта, калі вы не хочаце, каб імя класа супадала са значэннем. Калі nullвыкарыстоўваецца ў якасці ключа карты, ён не кампілюецца.
class Дадаткова нуль Імя згенераванага класа. Калі не прадугледжана і propertyз'яўляецца масівам радкоў, classпа змаўчанні будзе першым элементам propertyмасіва.
css-var Дадаткова false Лагічнае значэнне для стварэння зменных CSS замест правілаў 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,
)

Як зменная 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; }

Утыліты для зменных CSS

Усталюйце css-varлагічны параметр у значэнне, trueі API будзе генераваць лакальныя зменныя CSS для дадзенага селектара замест звычайных property: valueправілаў. Разгледзім нашы .text-opacity-*ўтыліты:

$utilities: (
  "text-opacity": (
    css-var: true,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

выхад:

.text-opacity-25 { --bs-text-opacity: .25; }
.text-opacity-50 { --bs-text-opacity: .5; }
.text-opacity-75 { --bs-text-opacity: .75; }
.text-opacity-100 { --bs-text-opacity: 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і вы атрымаеце .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ўтыліту з трыма значэннямі.

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

Змяніць утыліты

Змяніце існуючыя ўтыліты ў $utilitiesкарце па змаўчанні з дапамогай map-getі map-mergeфункцый. У прыведзеным ніжэй прыкладзе мы дадаем дадатковае значэнне widthўтылітам. Пачніце з ініцыяла map-merge, а затым пакажыце, якую ўтыліту вы хочаце змяніць. Адтуль атрымайце ўкладзеную "width"карту, map-getкаб атрымаць доступ і змяніць параметры і значэнні ўтыліты.

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

Уключыць спагадны

Вы можаце ўключыць адаптыўныя класы для існуючага набору ўтыліт, якія зараз не рэагуюць па змаўчанні. Напрыклад, каб зрабіць borderкласы спагаднымі:

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

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

Цяпер гэта будзе ствараць адаптыўныя варыяцыі .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/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Выдаліць камунальныя паслугі

Выдаліце ​​любыя ўтыліты па змаўчанні, усталяваўшы ключ групы на null. Напрыклад, каб выдаліць усе нашы widthўтыліты, стварыце $utilities map-mergeі дадайце "width": nullўнутр.

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

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

Выдаліць утыліту ў RTL

Некаторыя краёвыя выпадкі ўскладняюць стылізацыю справа справа , напрыклад, разрывы радкоў у арабскай мове. Такім чынам, утыліты можна выключыць з вываду RTL, усталяваўшы rtlопцыю false:

$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, дзякуючы дырэктыве кіравання RTLCSSremove .