Службовий 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
. Переконайтеся, що _utilities.scss
спершу імпортовано необхідні файли Sass і , а потім скористайтеся 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 { ... }
}
Перейменування утиліт
Відсутні утиліти версії 4 або використовуються інші правила іменування? 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
.