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

Служебный API

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

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

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

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

Утилиты переменных CSS

Установите css-varлогическую опцию, trueи API будет генерировать локальные переменные CSS для данного селектора вместо обычных property: valueправил. Обратите внимание на наши .text-opacity-*утилиты:

$utilities: (
  "text-opacity": (
    css-var: true,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

Выход:

.text-opacity-25 { --bs-text-opacity: .25; }
.text-opacity-50 { --bs-text-opacity: .5; }
.text-opacity-75 { --bs-text-opacity: .75; }
.text-opacity-100 { --bs-text-opacity: 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/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 .