API утилит

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

На этой странице

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

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

Опция	Тип	Значение по умолчанию	Описание
`property`	Обязательно	–	Название свойства, может быть строкой или массивом строк (например, горизонтальные отступы или поля).
`values`	Обязательно	–	Список значений или карта, если вы не хотите, чтобы имя класса совпадало со значением. Если `null` используется как ключ карты, `class` не добавляется к имени класса.
`class`	Опционально	null	Название генерируемого класса. Если не указано и `property` является массивом строк, `class` будет по умолчанию первым элементом массива `property`. Если не указано и `property` является строкой, ключи `values` используются для имен `class`.
`css-var`	Опционально	`false`	Логическое значение для генерации CSS-переменных вместо CSS-правил.
`css-variable-name`	Опционально	null	Пользовательское имя без префикса для CSS-переменной внутри набора правил.
`local-vars`	Опционально	null	Карта локальных CSS-переменных для генерации в дополнение к CSS-правилам.
`state`	Опционально	null	Список вариантов псевдоклассов (например, `: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 утилит, узнайте, как добавлять собственные пользовательские классы и изменять наши утилиты по умолчанию.

Переопределение утилит

Переопределяйте существующие утилиты, используя тот же ключ. Например, если вы хотите дополнительные отзывчивые классы утилит overflow, вы можете сделать это:

$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/variables-dark";
@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/variables-dark";
@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/variables-dark";
@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 { ... }
}

Переименование утилит

Не хватает утилит v4 или привыкли к другому соглашению об именовании? API утилит можно использовать для переопределения результирующего class данной утилиты — например, чтобы переименовать утилиты .ms-* в старые .ml-*:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@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";

Удаление утилит

Удалите любую из утилит по умолчанию с помощью функции Sass map-remove().

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

// Удалить несколько утилит со списком, разделенным запятыми
$utilities: map-remove($utilities, "width", "float");

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

Вы также можете использовать функцию Sass map-merge() и установить ключ группы в null для удаления утилиты.

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

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

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

Добавление, удаление, изменение

Вы можете добавлять, удалять и изменять много утилит одновременно с помощью функции Sass map-merge(). Вот как вы можете объединить предыдущие примеры в одну большую карту.

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

$utilities: map-merge(
  $utilities,
  (
    // Удалить утилиту `width`
    "width": null,
    // Сделать существующую утилиту отзывчивой
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
    // Добавить новые утилиты
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

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

Удаление утилиты в 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 благодаря директиве управления RTLCSS remove.