Перейти до основного вмісту Перейти до навігації документами
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. Переконайтеся, що _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 .