Sass

Utilize nossos arquivos Sass de origem para tirar proveito de variáveis, mapas, mixins e funções para ajudá-lo a criar mais rapidamente e personalizar seu projeto.

Nesta página

Utilize nossos arquivos Sass de origem para tirar proveito de variáveis, mapas, mixins e muito mais.

Estrutura do arquivo

Sempre que possível, evite modificar os arquivos principais do Bootstrap. Para Sass, isso significa criar sua própria folha de estilo que importa o Bootstrap para que você possa modificá-lo e estendê-lo. Supondo que você esteja usando um gerenciador de pacotes como o npm, você terá uma estrutura de arquivos parecida com esta:

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

Se você baixou nossos arquivos de origem e não está usando um gerenciador de pacotes, você desejará criar manualmente algo semelhante a essa estrutura, mantendo os arquivos de origem do Bootstrap separados dos seus.

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

Importando

No seu custom.scss, você importará os arquivos Sass de origem do Bootstrap. Você tem duas opções: incluir todo o Bootstrap ou escolher as peças que você precisa. Incentivamos o último, embora esteja ciente de que existem alguns requisitos e dependências em nossos componentes. Você também precisará incluir algum JavaScript para nossos plugins.

// Custom.scss
// Option A: Include all of Bootstrap

// Include any default variable overrides here (though functions won't be available)

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

// Then add additional custom code here

// Custom.scss
// Option B: Include parts of Bootstrap

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../node_modules/bootstrap/scss/functions";

// 2. Include any default variable overrides here

// 3. Include remainder of required Bootstrap stylesheets
@import "../node_modules/bootstrap/scss/variables";

// 4. Include any default map overrides here

// 5. Include remainder of required parts
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. Optionally include any other parts as needed
@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. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. Add additional custom code here

Com essa configuração, você pode começar a modificar qualquer uma das variáveis e mapas Sass em seu arquivo custom.scss. Você também pode começar a adicionar partes do Bootstrap na // Optionalseção conforme necessário. Sugerimos usar a pilha de importação completa do nosso bootstrap.scssarquivo como ponto de partida.

Padrões de variáveis

Cada variável Sass no Bootstrap inclui o !defaultsinalizador que permite substituir o valor padrão da variável em seu próprio Sass sem modificar o código-fonte do Bootstrap. Copie e cole variáveis conforme necessário, modifique seus valores e remova o !defaultsinalizador. Se uma variável já foi atribuída, ela não será reatribuída pelos valores padrão no Bootstrap.

Você encontrará a lista completa de variáveis do Bootstrap em scss/_variables.scss. Algumas variáveis são definidas como null, essas variáveis não geram a propriedade, a menos que sejam substituídas em sua configuração.

As substituições de variáveis devem vir após a importação de nossas funções, mas antes do restante das importações.

Aqui está um exemplo que altera o background-colorand colorpara <body>ao importar e compilar o Bootstrap via npm:

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

// Default variable overrides
$body-bg: #000;
$body-color: #111;

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

// Optional Bootstrap components here
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Repita conforme necessário para qualquer variável no Bootstrap, incluindo as opções globais abaixo.

Comece com o Bootstrap via npm com nosso projeto inicial! Vá para o repositório de modelos twbs/bootstrap-npm-starter para ver como construir e personalizar o Bootstrap em seu próprio projeto npm. Inclui compilador Sass, Autoprefixer, Stylelint, PurgeCSS e ícones de Bootstrap.

Mapas e loops

O Bootstrap inclui vários mapas Sass, pares de valores-chave que facilitam a geração de famílias de CSS relacionados. Usamos mapas Sass para nossas cores, pontos de interrupção de grade e muito mais. Assim como as variáveis Sass, todos os mapas Sass incluem o !defaultsinalizador e podem ser substituídos e estendidos.

Alguns de nossos mapas Sass são mesclados em mapas vazios por padrão. Isso é feito para permitir a expansão fácil de um determinado mapa Sass, mas tem o custo de tornar a remoção de itens de um mapa um pouco mais difícil.

Modificar mapa

Todas as variáveis no $theme-colorsmapa são definidas como variáveis independentes. Para modificar uma cor existente em nosso $theme-colorsmapa, adicione o seguinte ao seu arquivo Sass personalizado:

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

Mais tarde, essas variáveis são definidas no $theme-colorsmapa do Bootstrap:

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

Adicionar ao mapa

Adicione novas cores a $theme-colors, ou a qualquer outro mapa, criando um novo mapa Sass com seus valores personalizados e mesclando-o com o mapa original. Nesse caso, criaremos um novo $custom-colorsmapa e o mesclaremos com $theme-colors.

// Create your own map
$custom-colors: (
  "custom-color": #900
);

// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

Remover do mapa

Para remover cores de $theme-colors, ou de qualquer outro mapa, use map-remove. Esteja ciente de que você deve inserir $theme-colorsentre nossos requisitos logo após sua definição em variablese antes de seu uso em maps:

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";

$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";

// Optional
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Chaves necessárias

O Bootstrap assume a presença de algumas chaves específicas dentro dos mapas Sass conforme usamos e estendemos por nós mesmos. Conforme você personaliza os mapas incluídos, você pode encontrar erros onde a chave de um mapa Sass específico está sendo usada.

Por exemplo, usamos as teclas , e de primarypara successlinks , botões e estados de formulário. Substituir os valores dessas chaves não deve apresentar problemas, mas removê-los pode causar problemas de compilação do Sass. Nesses casos, você precisará modificar o código Sass que faz uso desses valores.danger$theme-colors

Funções

Cores

Ao lado dos mapas Sass que temos, as cores do tema também podem ser usadas como variáveis independentes, como $primary.

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

Você pode clarear ou escurecer as cores com Bootstrap tint-color()e shade-color()funções. Essas funções misturam cores com preto ou branco, diferentemente do nativo do Sass lighten()e darken()funções que alteram a luminosidade em uma quantidade fixa, o que muitas vezes não leva ao efeito desejado.

// 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));
}

Na prática, você chamaria a função e passaria os parâmetros de cor e peso.

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

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

Contraste de cores

Para atender aos requisitos de contraste da Web Content Accessibility Guidelines (WCAG) , os autores devem fornecer um contraste mínimo de cores de texto de 4,5:1 e um contraste mínimo de cores sem texto de 3:1 , com poucas exceções.

Para ajudar com isso, incluímos a color-contrastfunção no Bootstrap. Ele usa o algoritmo de taxa de contraste WCAG para calcular os limites de contraste com base na luminância relativa em um sRGBespaço de cores para retornar automaticamente uma cor de contraste clara ( #fff), escura ( #212529) ou preta ( #000) com base na cor base especificada. Esta função é especialmente útil para mixins ou loops onde você está gerando várias classes.

Por exemplo, para gerar amostras de cores do nosso $theme-colorsmapa:

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

Também pode ser usado para necessidades pontuais de contraste:

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

Você também pode especificar uma cor base com nossas funções de mapa de cores:

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

Escape SVG

Usamos a escape-svgfunção para escapar dos caracteres <, >e #para imagens de fundo SVG. Ao usar a escape-svgfunção, os URIs de dados devem ser citados.

Funções de adição e subtração

Usamos as funções adde subtractpara envolver a calcfunção CSS. O objetivo principal dessas funções é evitar erros quando um valor “sem unidade” 0é passado para uma calcexpressão. Expressões como calc(10px - 0)retornarão um erro em todos os navegadores, apesar de serem matematicamente corretas.

Exemplo onde o cálculo é válido:

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

.element {
  // Output calc(.25rem - 1px) is valid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output the same calc(.25rem - 1px) as above
  border-radius: subtract($border-radius, $border-width);
}

Exemplo em que o cálculo é inválido:

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

.element {
  // Output calc(.25rem - 0) is invalid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output .25rem
  border-radius: subtract($border-radius, $border-width);
}

Mixins

Nosso scss/mixins/diretório tem uma tonelada de mixins que alimentam partes do Bootstrap e também podem ser usados em seu próprio projeto.

Esquema de cores

Um mixin abreviado para a prefers-color-schemeconsulta de mídia está disponível com suporte para light, darke esquemas de cores personalizados.

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

.custom-element {
  @include color-scheme(dark) {
    // Insert dark mode styles here
  }

  @include color-scheme(custom-named-scheme) {
    // Insert custom color scheme styles here
  }
}