Sass

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

On this page

利用我们的源Sass文件来利用变量、Map、mixin等。

文件结构

尽可能避免修改引导程序的核心文件。对于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. 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. 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

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

编译

为了在浏览器中使用自定义的Sass代码作为CSS，你需要一个Sass编译器。 Sass作为CLI包提供，但你也可以使用其他构建工具，如[Gulp](https://gulpjs.com/）进行编译或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

有关你的选项的更多信息，请访问sas-lang.com/install和使用VS代码编译。

将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时更改＜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";

// 此处为可选引导组件
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

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

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

Map和循环

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

默认情况下，我们的一些Sass map会合并到空Map。这样做是为了方便地扩展给定的Sass Map，但代价是使Map中的_removing_项变得稍微困难一些。

修改Map

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

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

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

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

添加到Map

通过使用自定义值创建新的Sass Map并将其与原始Map合并，将新颜色添加到$theme-colors或任何其他Map。在这种情况下，我们将创建一个新的$custom-colors map，并将其与$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。请注意，你必须在variables中定义后和maps中使用前在我们的需求之间插入$theme-colors ：

// 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

必需的Key

Bootstrap假设在Sass映射中存在一些特定的Key，我们自己使用和扩展这些Key。当你自定义已包含的 Map 时，你可能会在使用特定Sass Map的Key时遇到错误。

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

Functions

Colors

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

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

你可以使用Bootstrap的tint-color()和shade-color())函数使颜色变亮或变暗。这些函数会将颜色与黑色或白色混合，不像Sass的原生lighten()和dark()函数，后者会将亮度改变固定的量，而这通常不会产生所需的效果。

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

颜色对比度

为了满足网络内容无障碍指南（WCAG）对比度要求，作者必须提供最低文本颜色对比度4.5:1和最小值非文本颜色对比度3:1，只有极少数例外。

为了帮助实现这一点，我们在Bootstrap中包含了 color-contrast 功能。它使用WCAG对比度算法，用于基于相对亮度计算对比度阈值以基于指定的基色自动返回亮(#fff)、暗(#212529)或黑(#000)对比色。这个函数对于生成多个类的mixins或循环特别有用。

例如，要从$theme-colors map生成色样（color swatches）：

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

It can also be used for one-off contrast needs:

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

你也可以使用我们的颜色map函数指定基本颜色（base color）：

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

Escape SVG

我们使用escape-svg函数来转义svg背景图像的<、>和#字符。使用escape-svg函数时，必须对数据URI进行引号引用。

Add和Subtract函数

我们使用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/目录有大量的mixin，这些mixin为Bootstrap的各个部分提供了支持，也可以在你自己的项目中使用。

配色方案

支持亮色和暗色配色方案，提供了 prefers-color-scheme 媒体查询的简写mixin。有关我们的颜色模式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
  }
}