Служебный API
Служебный API - это инструмент на основе Sass для создания служебных классов.
Утилиты Bootstrap создаются с помощью нашего служебного API и могут использоваться для изменения или расширения нашего набора служебных классов по умолчанию через Sass. Наш служебный API основан на серии карт и функций Sass для создания семейств классов с различными параметрами. Если Вы не знакомы с картами Sass, прочитайте официальную документацию Sass, чтобы начать работу.
Карта $utilities содержит все наши утилиты и позже объединяется с Вашей пользовательской картой $utilities, если она есть. Карта утилит содержит ключевой список групп утилит, которые принимают следующие параметры:
| Опция | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
property | Обязательно | – | Имя свойства. Это может быть строка или массив строк (например, горизонтальные отступы или поля). |
values | Обязательно | – | Список значений или карта, если вы не хотите, чтобы имя класса совпадало со значением. Если в качестве ключа карты используется null, class не добавляется перед именем класса. |
class | Необязательно | null | Имя сгенерированного класса. Если не указано, а свойство property является массивом строк, класс class по умолчанию будет первым элементом массива свойств property. Если не указано и property представляет собой строку, ключи values используются для имен class. |
css-var | Необязательно | false | Логическое значение для генерации переменных CSS вместо правил CSS. |
css-variable-name | Необязательно | null | Пользовательское имя без префикса для переменной CSS внутри набора правил. |
local-vars | Необязательно | null | Карта локальных переменных CSS для генерации в дополнение к правилам CSS. |
state | Необязательно | null | Список вариантов псевдокласса (например, :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:noneunderlineline-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:noneunderlineline-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;}Адаптивность
Добавьте логическое значение 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!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;}@mediaprint{.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:visiblehiddenscrollauto,),);Добавление утилит
Новые утилиты могут быть добавлены к карте по умолчанию $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:autopointergrab,)));@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";Удаление утилит
Удалите все стандартные утилиты с помощью Sass-функции map-remove().
@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";Вы также можете использовать Sass функцию map-merge() и установить для группового ключа значение 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";Добавление, удаление, изменение
Вы можете добавлять, удалять и изменять множество утилит одновременно с помощью Sass-функции map-merge(). Вот как вы можете объединить предыдущие примеры в одну большую карту.
@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:autopointergrab,)));@import"bootstrap/scss/utilities/api";Удаление утилит в RTL
Некоторые крайние случаи затрудняют стилизацию RTL, например, разрывы строк на арабском языке. Таким образом, утилиты можно исключить из вывода RTL, установив для опции rtl значение false:
$utilities:("word-wrap":(property:word-wrapword-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.