Службовий API

API утиліти — це інструмент на основі Sass для створення класів утиліт.

На цій сторінці

Утиліти Bootstrap створюються за допомогою нашого API утиліт і можуть використовуватися для зміни або розширення нашого стандартного набору класів утиліт через Sass. Наш API утиліти базується на серії карт і функцій Sass для генерації сімейств класів з різними параметрами. Якщо ви не знайомі з картами Sass, прочитайте офіційну документацію Sass , щоб почати.

Карта $utilitiesмістить усі наші утиліти та пізніше об’єднується з вашою спеціальною $utilitiesкартою, якщо вона є. Карта комунальних послуг містить перелік груп комунальних послуг із ключами, які приймають наступні параметри:

Варіант	Тип	Значення за замовчуванням	опис
`property`	вимагається	–	Ім'я властивості, це може бути рядок або масив рядків (наприклад, горизонтальні відступи або поля).
`values`	вимагається	–	Список значень або карта, якщо ви не хочете, щоб ім’я класу збігалося зі значенням. Якщо `null`використовується як ключ карти, `class`не додається до імені класу.
`class`	Додатково	нуль	Назва згенерованого класу. Якщо не вказано та `property`є масивом рядків, `class`за замовчуванням використовуватиметься перший елемент `property`масиву. Якщо не вказано та `property`є рядком, `values`ключі використовуються для `class`імен.
`css-var`	Додатково	`false`	Логічне значення для створення змінних CSS замість правил CSS.
`css-variable-name`	Додатково	нуль	Власне ім’я без префіксу для змінної 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; }

Якщо class: null, генерує класи для кожного з valuesключів:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Вихід:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

Утиліти змінних CSS

Встановіть css-varлогічний параметр, trueі API генеруватиме локальні змінні CSS для даного селектора замість звичайних property: valueправил. Додайте необов’язковий параметр css-variable-name, щоб встановити інше ім’я змінної CSS, ніж ім’я класу.

Розглянемо наші .text-opacity-*комунальні послуги. Якщо ми додамо css-variable-nameопцію, ми отримаємо настроюваний вихід.

$utilities: (
  "text-opacity": (
    css-var: true,
    css-variable-name: text-alpha,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

Вихід:

.text-opacity-25 { --bs-text-alpha: .25; }
.text-opacity-50 { --bs-text-alpha: .5; }
.text-opacity-75 { --bs-text-alpha: .75; }
.text-opacity-100 { --bs-text-alpha: 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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Змінити утиліти

Змініть наявні утиліти в типовій $utilitiesкарті за допомогою функцій map-getі map-merge. У наведеному нижче прикладі ми додаємо додаткові значення до widthутиліт. Почніть з ініціалу, map-mergeа потім укажіть, яку утиліту ви хочете змінити. Звідти витягніть вкладену "width"карту, map-getщоб отримати доступ і змінити параметри та значення утиліти.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@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%),
        ),
      ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Увімкнути реагування

Ви можете ввімкнути адаптивні класи для наявного набору утиліт, які наразі не адаптивні за замовчуванням. Наприклад, щоб зробити borderкласи адаптивними:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Тепер це створить адаптивні варіанти .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 { ... }
}

Перейменування утиліт

Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting class of a given utility—for example, to rename .ms-* utilities to oldish .ml-*:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Remove utilities

Remove any of the default utilities with the map-remove() Sass function.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

// Remove multiple utilities with a comma-separated list
$utilities: map-remove($utilities, "width", "float");

@import "bootstrap/scss/utilities/api";

You can also use the map-merge() Sass function and set the group key to null to remove the utility.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

@import "bootstrap/scss/utilities/api";

Add, remove, modify

You can add, remove, and modify many utilities all at once with the map-merge() Sass function. Here’s how you can combine the previous examples into one larger map.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    // Remove the `width` utility
    "width": null,

    // Make an existing utility responsive
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Add new utilities
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Remove utility in 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 .