Sass

定制Sass 源代码利用变量、映射(map)、混合(mixin) 和函数(function)来帮助您更快地构建和自定义您的项目。

内容提要

文件结构

尽可能避免修改 Bootstrap 的核心文件。对于 Sass ，有一个修改的变通方法：创建您自己的样式表， Bootstrap 导入，这样您就可以修改和扩展它了。假设您使用的是像 npm 这样的包管理器，您将拥有一个如下所示的文件结构：

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

如果您没有使用包管理器，并且已经下载了我们的源码文件，您将需要手动设置类似于该结构的东西，将 Bootstrap 的源文件与您自己的源文件分开。

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

引入

在您的 custom.scss 文件中，您需要导入 Bootstrap 的 Sass 源码文件。你有两个选择：包括所有的 Bootstrap，或者选择你需要的部分。我们鼓励后者，但请注意我们的组件之间存在一些要求和依赖关系。您还需要为我们的插件添加一些 JavaScript。

// 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";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 4. Include any optional Bootstrap CSS 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";

// 5. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 6. Add additional custom code here

设置好之后，您可以开始修改 custom.scss 中的任何 Sass 变量和映射。您也可以根据需要在 // Optional 下面添加您的自定义代码。在您刚开始使用Bootstrap的时候，我们建议导入完整的 bootstrap.scss 文件。

变量默认值

Bootstrap 中的每个 Sass 变量的定义都包含 !default 标志，允许您在自己的 Sass 代码中覆盖变量的默认值，而无需修改 Bootstrap 的源代码。根据需要复制和粘贴变量，修改它们的值，然后删除 !default 标志。

您将在 scss/_variables.scss 中找到完整的 Bootstrap 变量列表。一些变量设置为 null，这些变量不会输出任何内容，除非被您自定义的代码覆盖。

变量覆盖必须在我们的函数被导入之后，但在其余的导入之前。也就是在您的Sass自定义文件中应先写覆盖默认变量的语句，再引入 Bootstrap 的 Sass 变量定义文件。它不会被 Bootstrap 中的默认值重新赋值。

这是一个在通过 npm 导入和编译 Bootstrap 时更改 <body> 的 background-color 和 color 的示例：

// 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/mixins";
@import "../node_modules/bootstrap/scss/root";

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

可以根据需要重复 Bootstrap 中的任何变量，包括下面的全局选项。

在我们的入门项目中通过 npm 开始使用 Bootstrap！ 前往 twbs/bootstrap-npm-starter 模板仓库，了解如何在您自己的 npm 项目中构建和自定义 Bootstrap。包括 Sass 编译器、Autoprefixer、Stylelint、PurgeCSS 和 Bootstrap 图标。

映射(Maps)和循环(loops)

Bootstrap 包含一些 Sass 映射，键值对可以更轻松地生成相关 CSS 族。 Sass 映射用在我们的颜色、网格断点等地方。就像 Sass 变量一样，所有 Sass 映射都包含 !default 标志并且可以被覆盖和扩展。

默认情况下，我们的一些 Sass 映射会合并为空映射。这样做是为了便于扩展给定的 Sass 映射，但代价是使从映射中移除项目变得更加困难。

修改映射

$theme-colors 映射中的所有变量都定义为独立变量。要修改 $theme-colors 映射中的现有颜色，请将以下内容添加到您的自定义 Sass 文件中：

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

稍后，这些变量在 Bootstrap 的 $theme-colors 映射中设置：

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

添加到映射中

想要将新颜色添加到 $theme-colors 或任何其他映射中。需要使用自定义值创建新的 Sass 映射并将其与原始映射合并，在这里，我们将创建一个新的 $custom-colors 映射并将其与 $theme-colors 合并。

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

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

从映射中删除

要从 $theme-colors 或任何其他映射中删除颜色，请使用 map-remove。请注意，您必须在我们的//Required和// Optional之间插入它：

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

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

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

必须键

Bootstrap 假设 Sass 映射中存在一些特定的键，因为我们自己使用并扩展了这些键。当您自定义包含的映射时，您可能会遇到使用特定 Sass 映射键的错误。

例如，我们使用 $theme-colors 中的 primary、success 和 danger 键作为链接、按钮、表格状态。替换这些键的值应该没有问题，但删除它们可能会导致 Sass 编译问题。在这些情况下，您需要修改使用这些值的 Sass 代码。

函数(Functions)

颜色

除了我们拥有的 Sass 映射，主题颜色也可以用作独立变量，例如 $primary 。

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

您可以使用 Bootstrap 的 tint-color() 和 shade-color() 函数使颜色变亮或变暗。这些函数会将颜色与黑色或白色混合，不像 Sass 的原生 lighten() 和 darken() 函数会以固定的量改变亮度，而这通常不会得到期望的效果。

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

颜色对比度

为了满足 WCAG 2.0 颜色对比度的可访问性标准，作者必须提供对比度至少为 4.5:1，只有极少数例外。

我们在 Bootstrap 中包含的另一个功能是颜色对比功能，color-contrast。它利用 WCAG 2.0 算法根据 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 {
  // 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);
}

无效calc的示例：

$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

我们的 scss/mixins/ 目录有大量的 mixin，它们支撑着 Bootstrap 的各个部分，也可以在您自己的项目中使用。

Color schemes

prefers-color-scheme 媒体查询的 mixin 可用于支持 light、dark 和自定义颜色方案。

@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
  }
}