Bootstrap утилиты API

Утилиты Bootstrap создаются с помощью нашего utility API и могут использоваться для изменения или расширения нашего набора служебных классов по умолчанию через Sass. Наш utility API основан на серии карт Sass и функциях для создания семейств классов с различными опциями. Если вы не знакомы с Sass maps, прочтите официальную документацию по 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 параметра boolean значение 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
      )
    )
  )
);

Вывод:

.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; }

Состояния

Используйте опцию state для создания вариантов псевдоклассов. Примерами псевдоклассов являются :hover и :focus. Когда предоставляется список состояний, для этого псевдокласса создаются имена классов. Например, чтобы изменить прозрачность при наведении курсора мыши, добавьте state: hover и вы получите .opacity-hover:hover в вашем скомпилированном CSS.

$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; }

Требуется несколько псевдоклассов? Используйте список состояний, разделенных пробелом: state: hover focus.

Адаптивный

Добавьте 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

Теперь, когда вы знакомы с тем, как работает utilities 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 { ... }
}

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

Отсутствуют утилиты версии 4 или используется другое соглашение об именовании? Utilities 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, благодаря директиве управления remove.