Перейти к основному содержанию Перейти к навигации по документации
View on GitHub

Служебный API

Служебный API - это инструмент на основе Sass для создания служебных классов.

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

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

Опция Тип Описание
property Обязательно Имя свойства. Это может быть строка или массив строк (например, horizontal paddings (горизонтальные отступы) или margins (поля)).
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; }

Состояния

Используйте опцию 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; }
.opacity-25-hover:hover { opacity: .25; }
.opacity-50-hover:hover { opacity: .5; }
.opacity-75-hover:hover { opacity: .75; }
.opacity-100-hover:hover { opacity: 1; }

Адаптивные утилиты

Добавьте логическое значение responseive для создания адаптивных утилит (например, .opacity-md-25) для всех контрольных точек.

$utilities: (
  "opacity": (
    property: opacity,
    responsive: true,
    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; }

@media (min-width: 576px) {
  .opacity-sm-0 { opacity: 0; }
  .opacity-sm-25 { opacity: .25; }
  .opacity-sm-50 { opacity: .5; }
  .opacity-sm-75 { opacity: .75; }
  .opacity-sm-100 { opacity: 1; }
}

@media (min-width: 768px) {
  .opacity-md-0 { opacity: 0; }
  .opacity-md-25 { opacity: .25; }
  .opacity-md-50 { opacity: .5; }
  .opacity-md-75 { opacity: .75; }
  .opacity-md-100 { opacity: 1; }
}

@media (min-width: 992px) {
  .opacity-lg-0 { opacity: 0; }
  .opacity-lg-25 { opacity: .25; }
  .opacity-lg-50 { opacity: .5; }
  .opacity-lg-75 { opacity: .75; }
  .opacity-lg-100 { opacity: 1; }
}

@media (min-width: 1200px) {
  .opacity-xl-0 { opacity: 0; }
  .opacity-xl-25 { opacity: .25; }
  .opacity-xl-50 { opacity: .5; }
  .opacity-xl-75 { opacity: .75; }
  .opacity-xl-100 { opacity: 1; }
}

@media (min-width: 1400px) {
  .opacity-xxl-0 { opacity: 0; }
  .opacity-xxl-25 { opacity: .25; }
  .opacity-xxl-50 { opacity: .5; }
  .opacity-xxl-75 { opacity: .75; }
  .opacity-xxl-100 { opacity: 1; }
}

Замена утилит

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

$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; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

@media print {
  .opacity-print-0 { opacity: 0; }
  .opacity-print-25 { opacity: .25; }
  .opacity-print-50 { opacity: .5; }
  .opacity-print-75 { opacity: .75; }
  .opacity-print-100 { opacity: 1; }
}

Использование API

Теперь, когда Вы знакомы с тем, как работает API утилит, узнайте, как добавлять свои собственные классы и изменять наши утилиты по умолчанию.

Добавление утилит

Новые утилиты могут быть добавлены к карте по умолчанию $utilities с помощью map-merge. Убедитесь, что наши необходимые файлы Sass и _utilities.scss сначала импортированы, а затем используйте 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%),
        ),
      ),
    ),
  )
);

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

Отсутствуют утилиты v4 или Вы привыкли к другому соглашению об именах? API утилит можно использовать для переопределения результирующего class данной утилиты - например, чтобы переименовать утилиты .ms-* в старые .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, благодаря управляющей директиве RTLCSS remove.