Служебный API

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

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

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

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

Вариант	Тип	Описание
`property`	Необходимый	Имя свойства, это может быть строка или массив строк (например, горизонтальные отступы или поля).
`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; }

Пользовательский префикс класса

Используйте classпараметр для изменения префикса класса, используемого в скомпилированном CSS:

$utilities: (
  "opacity": (
    property: opacity,
    class: o,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
 );

Выход:

.o-0 { opacity: 0; }
.o-25 { opacity: .25; }
.o-50 { opacity: .5; }
.o-75 { opacity: .75; }
.o-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 !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; }
}

Изменение утилит

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

$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 !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карте по умолчанию с помощью файла 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%),
        ),
      ),
    ),
  )
);

Включить отзывчивый

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

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

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

Теперь это будет генерировать адаптивные варианты .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-*утилит в oldish .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 благодаря управляющей директиве RTLCSSremove .