Sass

利用我们的 Sass 源文件，利用变量、映射、mixins 和函数，帮助您更快地构建和定制您的项目。

On this page

利用我们的 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 中，您将导入 Bootstrap 的 Sass 源文件。您有两种选择：包含整个 Bootstrap，或者选择您需要的部分。我们鼓励您选择后者，但请注意我们的组件有一些要求和依赖性。您还需要为我们的插件包含一些 JavaScript。

// Custom.scss
// 选项 A: 包含所有的 Bootstrap

// 在此处包含任何默认变量重载（尽管函数将不可用）

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

// 然后在此处添加其他自定义代码

// Custom.scss
// 选项 B: 包含部分 Bootstrap

// 1. 首先包含函数（以便您可以处理颜色、SVG、计算等）。
@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. 可选择最后加入实用程序应用程序接口，以便根据`_utilities.scss`中的 Sass 映射生成类
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. 在此处添加其他自定义代码

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

编译

要在浏览器中使用自定义 Sass 代码作为 CSS，你需要一个 Sass 编译器。Sass 以 CLI 软件包的形式发布，但你也可以使用其他编译工具，如 Gulp 或 Webpack 或 GUI 应用程序来编译。一些集成开发环境也内置了 Sass 编译器，或作为可下载的扩展。

我们喜欢使用 CLI 来编译 Sass，但你也可以使用自己喜欢的方法。在命令行中运行以下命令：

# 全局安装 Sass
npm install -g sass

# 查看自定义 Sass 的变化，并将其编译为 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 变量的完整列表。有些变量被设置为 “空”，这些变量不会输出属性，除非在配置中被重载。

变量重载必须在函数导入之后，其他导入之前进行。

下面是通过 npm 导入和编译 Bootstrap 时更改 <body> 的 background-color 和 color 的示例：

// 必要的
@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";
// 等等

对 Bootstrap 中的任何变量，包括下面的全局选项，重复上述步骤。

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

映射和循环

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 合并。

// 创建自己的 map
$custom-colors: (
  "custom-color": #900
);

// 合并 maps
$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";
// 等等

必要的键

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

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

函数

颜色

除了Sass maps之外，主题颜色还可以作为独立变量使用，比如$primary。

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

您可以使用 Bootstrap 的tint-color()和shade-color()函数来淡化或加深颜色。这些函数会将颜色与黑色或白色混合，这与 Sass 本机的lighten()和darken()函数不同，后者会按固定的量改变颜色的明暗度，这往往达不到预期效果。

shift-color() 结合了这两个函数，如果权重为正，则对颜色进行加深着色；如果权重为负，则对颜色进行淡化着色。

scss/_functions.zh.scss

// 淡化调色：将一种颜色与白色混合
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// 给颜色加深着色：将一种颜色与黑色混合
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

// 如果权重为正数，则加深着色，否则淡化着色
@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）对比色。该函数对于生成多个类的混合或循环尤其有用。

例如，从我们的 $theme-colors 映射生成色板：

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

它还可用于一次性对比需求：

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

您还可以使用我们的颜色映射功能指定基色：

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

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

Mixins

我们的 scss/mixins/ 目录中有大量的 mixins，它们为 Bootstrap 的某些部分提供了支持，也可以在您自己的项目中使用。

配色方案

为 prefers-color-scheme 媒体查询提供了一个速记混合插件，支持 light和 dark 配色方案。有关色彩模式混合插件的信息，请参阅色彩模式文档。

scss/mixins/_color-scheme.scss

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

.custom-element {
  @include color-scheme(light) {
    // 这里 添加浅色模式的样式
  }

  @include color-scheme(dark) {
    // 这里 添加深色模式的样式
  }
}