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-*
на помощни програми на 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
.