API утилит

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

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

Описание 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. Убедитесь, что сначала импортированы необходимые 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";

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

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

@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";

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

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

Вы также можете использовать функцию map-merge() Sass и установить ключ группы в 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";

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

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

@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,
  (
    // 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";

Удаление утилиты в 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.