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

Утыліта API

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

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

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

Варыянт Тып Апісанне
property абавязковы Імя ўласцівасці, гэта можа быць радок або масіў радкоў (напрыклад, гарызантальныя запаўненні або палі).
values абавязковы Спіс значэнняў або карта, калі вы не хочаце, каб імя класа супадала са значэннем. Калі nullвыкарыстоўваецца ў якасці ключа карты, ён не кампілюецца.
class Дадаткова Пераменная для імя класа, калі вы не хочаце, каб яно было такім жа, як уласцівасць. У выпадку, калі вы не ўвялі classключ, а propertyключ з'яўляецца масівам радкоў, імя класа будзе першым элементам propertyмасіва.
state Дадаткова Спіс варыянтаў псеўдакласаў, такіх як :hoverабо :focusдля стварэння для ўтыліты. Няма значэння па змаўчанні.
responsive Дадаткова Лагічнае значэнне, якое паказвае, ці трэба ствараць адаптыўныя класы. falseпа змаўчанні.
rfs Дадаткова Лагічнае значэнне для ўключэння змены маштабу вадкасці. Зірніце на старонку RFS , каб даведацца, як гэта працуе. falseпа змаўчанні.
print Дадаткова Лагічнае значэнне, якое паказвае, ці трэба ствараць класы друку. falseпа змаўчанні.
rtl Дадаткова Лагічнае значэнне, якое паказвае, ці трэба захоўваць утыліту ў RTL. trueпа змаўчанні.

Тлумачэнне 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; }

Карыстальніцкі прэфікс класа

Выкарыстоўвайце classопцыю, каб змяніць прэфікс класа, які выкарыстоўваецца ў скампіляваным CSS:

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

выхад:

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

дзяржавы

Выкарыстоўвайце 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; }
}

Змена камунальных паслуг

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

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

Уключэнне 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карту па змаўчанні з дапамогай 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-*утыліты ў oldish .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, усталяваўшы 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 .