Утыліта 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
.