Sass

使用我们的源 Sass 文件，利用变量、映射、mixin 和函数来帮助你更快地构建并自定义项目。

本页目录

利用我们的源 Sass 文件来使用变量、映射、mixin等功能。

在使用最新版本的 Dart Sass 编译源 Sass 文件时，会显示 Sass 弃用警告。这不会阻止 Bootstrap 的编译或使用。我们正在着手长期解决，但在此期间，这些弃用提示可以忽略。

文件结构

尽可能避免修改 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 中，你将导入 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 (including any separate color mode stylesheets)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
// 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. Include any other optional stylesheet partials as desired; list below is not inclusive of all available stylesheets
@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

有了这个设置后，你可以开始修改你 custom.scss 中的任何 Sass 变量和映射。你也可以根据需要开始在 // Optional 部分添加 Bootstrap 的部分内容。我们建议将 bootstrap.scss 文件中的完整导入堆栈作为起点使用。

编译

为了在浏览器中将自定义 Sass 代码作为 CSS 使用，你需要一个 Sass 编译器。Sass 以 CLI 包的形式提供，但你也可以使用其他构建工具如 Gulp 或 Webpack 进行编译，或者使用 GUI 应用程序。一些 IDE 也内置了 Sass 编译器，或者可以通过可下载的扩展来使用。

我们喜欢使用 CLI 来编译我们的 Sass，但你可以使用任何你喜欢的方法。从命令行运行以下命令：

# Install Sass globally
npm install -g sass

# Watch your custom Sass for changes and compile it to CSS
sass --watch ./scss/custom.scss ./css/custom.css

在 sass-lang.com/install 和使用 VS Code 编译中了解更多关于你的选项。

使用 Bootstrap 配合其他构建工具？ 可以考虑阅读我们关于使用 Webpack、Parcel 或 Vite 进行编译的指南。我们在 GitHub 的示例仓库中也提供了适用于生产环境的演示。

包括

一旦你的 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>

变量默认值

Bootstrap 中的每个 Sass 变量都包含 !default 标志，允许你在自己的 Sass 中覆盖变量的默认值，而无需修改 Bootstrap 的源代码。根据需要复制和粘贴变量，修改它们的值，并移除 !default 标志。如果变量已经被赋值，那么它不会被 Bootstrap 的默认值重新赋值。

你可以在 scss/_variables.scss 中找到 Bootstrap 变量的完整列表。某些变量被设置为 null，这些变量除非在你的配置中被覆盖，否则不会输出属性。

变量覆盖必须在导入我们的函数之后，但在其他导入之前进行。

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

// 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/variables-dark";
@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

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

通过我们的入门项目使用 npm 开始使用 Bootstrap！ 前往 Sass & JS 示例模板仓库，看看如何在你自己的 npm 项目中构建和自定义 Bootstrap。包括 Sass 编译器、Autoprefixer、Stylelint、PurgeCSS 和 Bootstrap 图标。

Map 和循环

Bootstrap 包含少量的 Sass 映射，即键值对，使生成相关 CSS 家族更加容易。我们将 Sass 映射用于颜色、网格断点等。就像 Sass 变量一样，所有 Sass 映射都包含 !default 标志，并且可以被覆盖和扩展。

我们的一些 Sass 映射默认会合并到空映射中。这么做是为了便于扩展特定的 Sass 映射，但代价是从映射中移除项目会稍微困难一些。

修改 Map

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

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

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

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

添加到 Map

通过创建一个包含自定义值的新 Sass 映射并将其与原始映射合并，可以向 $theme-colors 或任何其他映射添加新颜色。在这种情况下，我们将创建一个新的 $custom-colors 映射并将其与 $theme-colors 合并。

// Create your own map
$custom-colors: (
  "custom-color": #900
);
// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

从Map上移除

去除颜色 $theme-colors，或任何其他Map，使用 map-remove请注意，你必须插入 $theme-colors 在其定义之后不久，我们的要求之间 variables 以及在其使用之前 maps:

// Required
@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";
// Optional
@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() 通过在权重为正时加深颜色，在权重为负时调亮颜色来结合这两个功能。

scss/_functions.scss

// 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，几乎没有例外。

为了帮助实现这一点，我们在 Bootstrap 中加入了 color-contrast 函数。它使用 WCAG 对比度比率算法，根据相对亮度在 sRGB 颜色空间中计算对比度阈值，以根据指定的基础颜色自动返回浅色 (#fff)、深色 (#212529) 或黑色 (#000) 对比颜色。这个函数对于生成多个类的 mixin 或循环尤其有用。

例如，要从我们的$theme-colorsMap生成颜色样本：

@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 函数来包装 CSS 的 calc 函数。这些函数的主要目的是在将“无单位”的 0 值传入 calc 表达式时避免错误。像 calc(10px - 0) 这样的表达式在所有浏览器中都会返回错误，尽管在数学上是正确的。

计算有效的示例：

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

计算无效的示例：

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

mixin

我们的 scss/mixins/ 目录有大量的 mixin，这些 mixin 驱动了 Bootstrap 的部分功能，也可以在你自己的项目中使用。

配色方案

提供prefers-color-scheme媒体查询的简写mixin，并支持light和dark配色方案。有关我们的配色模式mixin的信息，请参阅配色模式文档。

scss/mixins/_color-scheme.scss

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

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