Sass

Используйте наши исходные файлы Sass, чтобы воспользоваться переменными, картами, миксинами и многим другим.

Структура файлов

По возможности избегайте изменения основных файлов Bootstrap. Для Sass это означает создание вашей собственной таблицы стилей, которая импортирует Bootstrap, чтобы вы могли изменять и расширять его. Предполагая, что вы используете менеджер пакетов, такой как npm, у вас будет структура файлов, которая выглядит так:

your-project/
├── scss/
│   └── custom.scss
└── node_modules/
│   └── bootstrap/
│       ├── js/
│       └── scss/
└── index.html

Если вы скачали наши исходные файлы и не используете менеджер пакетов, вы захотите вручную создать что-то похожее на эту структуру, держа исходные файлы Bootstrap отдельно от ваших собственных.

your-project/
├── scss/
│   └── custom.scss
├── bootstrap/
│   ├── js/
│   └── scss/
└── index.html

Импорт

В вашем custom.scss вы будете импортировать исходные файлы Sass Bootstrap. У вас есть два варианта: включить весь Bootstrap или выбрать части, которые вам нужны. Мы рекомендуем последнее, хотя имейте в виду, что есть некоторые требования и зависимости между нашими компонентами. Вам также потребуется включить некоторый JavaScript для наших плагинов.

// Custom.scss
// Вариант A: Включить весь Bootstrap

// Включите здесь любые переопределения переменных по умолчанию (хотя функции не будут доступны)

@import "../node_modules/bootstrap/scss/bootstrap";

// Затем добавьте здесь дополнительный пользовательский код

// Custom.scss
// Вариант B: Включить части Bootstrap

// 1. Сначала включите функции (чтобы вы могли манипулировать цветами, SVG, calc и т.д.)
@import "../node_modules/bootstrap/scss/functions";

// 2. Включите здесь любые переопределения переменных по умолчанию

// 3. Включите остальные обязательные таблицы стилей Bootstrap (включая любые отдельные таблицы стилей цветовых режимов)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. Включите здесь любые переопределения карт по умолчанию

// 5. Включите остальные обязательные части
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. Включите любые другие опциональные части таблиц стилей по желанию; список ниже не включает все доступные таблицы стилей
@import "../node_modules/bootstrap/scss/utilities";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/containers";
@import "../node_modules/bootstrap/scss/grid";
@import "../node_modules/bootstrap/scss/helpers";
// ...

// 7. Опционально включите API утилит последним для генерации классов на основе карты Sass в `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. Добавьте здесь дополнительный пользовательский код

С этой настройкой на месте вы можете начать изменять любые переменные и карты Sass в вашем custom.scss. Вы также можете начать добавлять части Bootstrap под раздел // Optional по мере необходимости. Мы предлагаем использовать полный стек импорта из нашего файла bootstrap.scss в качестве отправной точки.

Компиляция

Чтобы использовать ваш пользовательский код Sass как CSS в браузере, вам нужен компилятор Sass. Sass поставляется как пакет CLI, но вы также можете компилировать его с другими инструментами сборки, такими как Gulp или Webpack, или с GUI приложениями. Некоторые IDE также имеют встроенные компиляторы Sass или в виде загружаемых расширений.

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

# Установить Sass глобально
npm install -g sass

# Отслеживать изменения в вашем пользовательском Sass и компилировать его в CSS
sass --watch ./scss/custom.scss ./css/custom.css

Узнайте больше о ваших вариантах на sass-lang.com/install и компиляции с VS Code.

Включение

После того как ваш CSS скомпилирован, вы можете включить его в ваши HTML файлы. Внутри вашего index.html вы захотите включить ваш скомпилированный CSS файл. Убедитесь, что обновите путь к вашему скомпилированному CSS файлу, если вы его изменили.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Custom Bootstrap</title>
    <link href="/css/custom.css" rel="stylesheet">
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

Переменные по умолчанию

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

Вы найдете полный список переменных Bootstrap в scss/_variables.scss. Некоторые переменные установлены в null, эти переменные не выводят свойство, если они не переопределены в вашей конфигурации.

Переопределения переменных должны идти после импорта наших функций, но перед остальными импортами.

Вот пример, который изменяет background-color и color для <body> при импорте и компиляции Bootstrap через npm:

// Обязательно
@import "../node_modules/bootstrap/scss/functions";

// Переопределения переменных по умолчанию
$body-bg: #000;
$body-color: #111;

// Обязательно
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Опциональные компоненты Bootstrap здесь
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Повторите по мере необходимости для любой переменной в Bootstrap, включая глобальные опции ниже.

Карты и циклы

Bootstrap включает несколько карт Sass, пары ключ-значение, которые упрощают генерацию семейств связанного CSS. Мы используем карты Sass для наших цветов, контрольных точек сетки и многого другого. Как и переменные Sass, все карты Sass включают флаг !default и могут быть переопределены и расширены.

Некоторые из наших карт Sass по умолчанию объединяются с пустыми. Это сделано для облегчения расширения данной карты Sass, но это происходит за счет того, что удаление элементов из карты становится немного более сложным.

Изменение карты

Все переменные в карте $theme-colors определены как отдельные переменные. Чтобы изменить существующий цвет в нашей карте $theme-colors, добавьте следующее в ваш пользовательский файл Sass:

$primary: #0074d9;
$danger: #ff4136;

Позже эти переменные устанавливаются в карте $theme-colors Bootstrap:

$theme-colors: (
  "primary": $primary,
  "danger": $danger
);

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

Добавьте новые цвета в $theme-colors или любую другую карту, создав новую карту Sass с вашими пользовательскими значениями и объединив её с исходной картой. В этом случае мы создадим новую карту $custom-colors и объединим её с $theme-colors.

// Создайте вашу собственную карту
$custom-colors: (
  "custom-color": #900
);

// Объедините карты
$theme-colors: map-merge($theme-colors, $custom-colors);

Удаление из карты

Чтобы удалить цвета из $theme-colors или любой другой карты, используйте map-remove. Обратите внимание, что вы должны вставить $theme-colors между нашими требованиями сразу после её определения в variables и перед её использованием в maps:

// Обязательно
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Опционально
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Обязательные ключи

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

Например, мы используем ключи primary, success и danger из $theme-colors для ссылок, кнопок и состояний форм. Замена значений этих ключей не должна представлять проблем, но их удаление может вызвать проблемы компиляции Sass. В таких случаях вам нужно будет изменить код Sass, который использует эти значения.

Функции

Цвета

Помимо карт Sass, которые у нас есть, цвета темы также могут использоваться как отдельные переменные, например $primary.

.custom-element {
  color: $gray-100;
  background-color: $dark;
}

Вы можете осветлить или затемнить цвета с помощью функций Bootstrap tint-color() и shade-color(). Эти функции смешивают цвета с черным или белым, в отличие от родных функций Sass lighten() и darken(), которые изменяют яркость на фиксированную величину, что часто не приводит к желаемому эффекту.

shift-color() объединяет эти две функции, затемняя цвет, если вес положительный, и осветляя цвет, если вес отрицательный.

// Tint a color: mix a color with white
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// Shade a color: mix a color with black
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

// Shade the color if the weight is positive, else tint it
@function shift-color($color, $weight) {
  @return if($weight > 0, shade-color($color, $weight), tint-color($color, -$weight));
}

На практике вы бы вызвали функцию и передали параметры цвета и веса.

.custom-element {
  color: tint-color($primary, 10%);
}

.custom-element-2 {
  color: shade-color($danger, 30%);
}

.custom-element-3 {
  color: shift-color($success, 40%);
  background-color: shift-color($success, -60%);
}

Контрастность цвета

Чтобы соответствовать требованиям контрастности Руководящих принципов доступности веб-контента (WCAG), авторы должны обеспечивать минимальную контрастность цвета текста 4.5:1 и минимальную контрастность нетекстового цвета 3:1, с очень немногими исключениями.

Чтобы помочь с этим, мы включили функцию color-contrast в Bootstrap. Она использует алгоритм коэффициента контрастности WCAG для вычисления порогов контрастности на основе относительной яркости в цветовом пространстве sRGB, чтобы автоматически возвращать светлый (#fff), темный (#212529) или черный (#000) контрастный цвет на основе указанного базового цвета. Эта функция особенно полезна для миксинов или циклов, где вы генерируете несколько классов.

Например, чтобы генерировать цветовые образцы из нашей карты $theme-colors:

@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-contrast($value);
  }
}

Она также может использоваться для одноразовых потребностей в контрастности:

.custom-element {
  color: color-contrast(#000); // returns `color: #fff`
}

Вы также можете указать базовый цвет с помощью наших функций цветовых карт:

.custom-element {
  color: color-contrast($dark); // returns `color: #fff`
}

Экранирование SVG

Мы используем функцию escape-svg для экранирования символов <, > и # для фоновых изображений SVG. При использовании функции escape-svg URI данных должны быть в кавычках.

Функции Add и Subtract

Мы используем функции add и subtract для обертывания CSS функции calc. Основная цель этих функций — избежать ошибок, когда "безразмерное" значение 0 передается в выражение calc. Выражения типа calc(10px - 0) вернут ошибку во всех браузерах, несмотря на математическую корректность.

Пример, где calc валиден:

$border-radius: .25rem;
$border-width: 1px;

.element {
  // Вывод calc(.25rem - 1px) валиден
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Вывод тот же calc(.25rem - 1px), что и выше
  border-radius: subtract($border-radius, $border-width);
}

Пример, где calc невалиден:

$border-radius: .25rem;
$border-width: 0;

.element {
  // Вывод calc(.25rem - 0) невалиден
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Вывод .25rem
  border-radius: subtract($border-radius, $border-width);
}

Миксины

Наша директория scss/mixins/ содержит множество миксинов, которые питают части Bootstrap и также могут использоваться в вашем собственном проекте.

Цветовые схемы

Сокращенный миксин для медиа-запроса prefers-color-scheme доступен с поддержкой цветовых схем light и dark. См. документацию по цветовым режимам для информации о нашем миксине цветового режима.

@mixin color-scheme($name) {
  @media (prefers-color-scheme: #{$name}) {
    @content;
  }
}

.custom-element {
  @include color-scheme(light) {
    // Вставьте здесь стили светлого режима
  }

  @include color-scheme(dark) {
    // Вставьте здесь стили темного режима
  }
}