Skip to main content Skip to docs navigation
View on GitHub

Sass

Utilize our source Sass files to take advantage of variables, maps, mixins, and functions to help you build faster and customize your project.利用我们的源Sass文件利用变量、映射、混合和函数来帮助您更快地构建和自定义项目。

On this page本页内容

Utilize our source Sass files to take advantage of variables, maps, mixins, and more.利用我们的源Sass文件来利用变量、映射、混合等。

File structure文件结构

Whenever possible, avoid modifying Bootstrap’s core files. 尽可能避免修改Bootstrap的核心文件。For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. 对于Sass，这意味着创建您自己的样式表来导入Bootstrap，以便您可以修改和扩展它。Assuming you’re using a package manager like npm, you’ll have a file structure that looks like this:假设您使用的是像npm这样的包管理器，那么您的文件结构如下所示：

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

If you’ve downloaded our source files and aren’t using a package manager, you’ll want to manually setup something similar to that structure, keeping Bootstrap’s source files separate from your own.如果您已经下载了我们的源文件，并且没有使用包管理器，那么您将需要手动设置类似于该结构的内容，将Bootstrap的源文件与您自己的源文件分开。

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

Importing导入

In your custom.scss, you’ll import Bootstrap’s source Sass files. 在custom.scs中，您将导入Bootstrap的源Sass文件。You have two options: include all of Bootstrap, or pick the parts you need. 您有两个选择：包括所有Bootstrap，或选择您需要的部分。We encourage the latter, though be aware there are some requirements and dependencies across our components. 我们鼓励后者，但请注意，我们的组件之间存在一些需求和依赖关系。You also will need to include some JavaScript for our plugins.您还需要为我们的插件包含一些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 `_utililies.scss`
@import "../node_modules/bootstrap/scss/utilities/api";
// 6. Add additional custom code here

With that setup in place, you can begin to modify any of the Sass variables and maps in your custom.scss. 设置就绪后，您可以开始修改custom.scss中的任何Sass变量和映射。You can also start to add parts of Bootstrap under the // Optional section as needed. 您还可以根据需要开始在// Optional部分下添加Bootstrap的部分。We suggest using the full import stack from our bootstrap.scss file as your starting point.我们建议使用bootstrap.scss文件中的完整导入堆栈作为起点。

Variable defaults变量默认值

Every Sass variable in Bootstrap includes the !default flag allowing you to override the variable’s default value in your own Sass without modifying Bootstrap’s source code. Bootstrap中的每个Sass变量都包括!default标志，允许您在自己的Sass中覆盖变量的默认值，而无需修改Bootstrap程序的源代码。Copy and paste variables as needed, modify their values, and remove the !default flag. 根据需要复制和粘贴变量，修改其值，并删除!default标志。If a variable has already been assigned, then it won’t be re-assigned by the default values in Bootstrap.如果一个变量已经被赋值，那么它将不会被Bootstrap中的默认值重新赋值。

You will find the complete list of Bootstrap’s variables in scss/_variables.scss. 您将在scss/_variables.scss中找到Bootstrap变量的完整列表。Some variables are set to null, these variables don’t output the property unless they are overridden in your configuration.某些变量设置为null，除非在配置中重写，否则这些变量不会输出属性。

Variable overrides must come after our functions are imported, but before the rest of the imports.变量重写必须在函数导入之后，但在其余导入之前。

Here’s an example that changes the background-color and color for the <body> when importing and compiling Bootstrap via npm:下面是一个通过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

Repeat as necessary for any variable in Bootstrap, including the global options below.根据需要对Bootstrap中的任何变量重复此操作，包括下面的全局选项。

Get started with Bootstrap via npm with our starter project!使用我们的入门项目，通过npm开始Bootstrap！ Head to the twbs/bootstrap-npm-starter template repository to see how to build and customize Bootstrap in your own npm project. 前往twbs/bootstrap-npm-starter模板库，了解如何在您自己的npm项目中构建和自定义Bootstrap。Includes Sass compiler, Autoprefixer, Stylelint, PurgeCSS, and Bootstrap Icons.包括Sass编译器、Autoprefixer、Stylelint、PurgeCSS和Bootstrap图标。

Maps and loops映射和循环

Bootstrap includes a handful of Sass maps, key value pairs that make it easier to generate families of related CSS. Bootstrap包括一些Sass映射，它们是键值对，使得生成相关CSS族更加容易。We use Sass maps for our colors, grid breakpoints, and more. 我们对颜色、网格断点等使用Sass贴图。Just like Sass variables, all Sass maps include the !default flag and can be overridden and extended.就像Sass变量一样，所有Sass映射都包含!default标志，可以覆盖和扩展。

Some of our Sass maps are merged into empty ones by default. 默认情况下，我们的一些Sass映射合并为空映射。This is done to allow easy expansion of a given Sass map, but comes at the cost of making removing items from a map slightly more difficult.这样做是为了方便地扩展给定的Sass映射，但代价是使从映射中删除项目稍微困难一些。

Modify map修改映射

All variables in the $theme-colors map are defined as standalone variables. $theme-colors映射中的所有变量都定义为独立变量。To modify an existing color in our $theme-colors map, add the following to your custom Sass file:要修改$theme-colors映射中的现有颜色，请将以下内容添加到自定义Sass文件中：

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

Later on, these variables are set in Bootstrap’s $theme-colors map:稍后，这些变量将在Bootstrap的$theme-colors映射中设置：

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

Add to map添加到映射

Add new colors to $theme-colors, or any other map, by creating a new Sass map with your custom values and merging it with the original map. 通过使用自定义值创建新的Sass贴图并将其与原始贴图合并，向$theme-colors或任何其他贴图添加新颜色。In this case, we’ll create a new $custom-colors map and merge it with $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);

Remove from map

To remove colors from $theme-colors, or any other map, use map-remove. 要从$theme-colors或任何其他映射中删除颜色，请使用map-remove。Be aware you must insert it between our requirements and options:请注意，您必须将其插入我们的要求和选项之间：

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

Required keys所需键

Bootstrap assumes the presence of some specific keys within Sass maps as we used and extend these ourselves. Bootstrap假设在我们自己使用和扩展Sass映射时，Sass映射中存在一些特定的键。As you customize the included maps, you may encounter errors where a specific Sass map’s key is being used.自定义包含的映射时，在使用特定Sass映射的密钥时可能会遇到错误。

For example, we use the primary, success, and danger keys from $theme-colors for links, buttons, and form states. 例如，我们使用$theme-colors中的primary、success和danger键作为链接、按钮和表单状态。Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues. 替换这些键的值不会出现问题，但是删除它们可能会导致Sass编译问题。In these instances, you’ll need to modify the Sass code that makes use of those values.在这些情况下，您需要修改使用这些值的Sass代码。

Functions函数

Colors颜色

Next to the Sass maps we have, theme colors can also be used as standalone variables, like $primary.除了我们拥有的Sass映射之外，主题颜色还可以用作独立变量，如$primary。

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

You can lighten or darken colors with Bootstrap’s tint-color() and shade-color() functions. 可以使用Bootstrap的tint-color()和shade-color()函数使颜色变亮或变暗。These functions will mix colors with black or white, unlike Sass' native lighten() and darken() functions which will change the lightness by a fixed amount, which often doesn’t lead to the desired effect.这些函数会将颜色与黑色或白色混合，这与Sass的原生light()和darken()函数不同，Sass的原生函数会将亮度更改固定数量，这通常不会产生所需的效果。

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

In practice, you’d call the function and pass in the color and weight parameters.实际上，您需要调用该函数并传入颜色和权重参数。

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

Color contrast颜色对比度

In order to meet WCAG 2.0 accessibility standards for color contrast, authors must provide a contrast ratio of at least 4.5:1, with very few exceptions.为了满足WCAG 2.0颜色对比的可访问性标准，作者必须提供至少4.5:1的对比度，很少有例外。

An additional function we include in Bootstrap is the color contrast function, color-contrast. 我们在Bootstrap中包含的另一个功能是颜色对比度函数，即color-contrast。It utilizes the WCAG 2.0 algorithm for calculating contrast thresholds based on relative luminance in a sRGB colorspace to automatically return a light (#fff), dark (#212529) or black (#000) contrast color based on the specified base color. 它利用WCAG 2.0算法根据sRGB颜色空间中的相对亮度计算对比度阈值，以根据指定的基色自动返回明度（#fff）、暗度（#212529）或黑色（#000）对比度颜色。This function is especially useful for mixins or loops where you’re generating multiple classes.此函数对于生成多个类的混合或循环特别有用。

For example, to generate color swatches from our $theme-colors map:例如，要从$theme-colors映射生成色样，请执行以下操作：

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

You can also specify a base color with our color map functions:您还可以使用我们的颜色贴图功能指定基础颜色：

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

Escape SVG转义SVG

We use the escape-svg function to escape the <, > and # characters for SVG background images. 我们使用escape-svg函数来转义SVG背景图像的<、>和#字符。When using the escape-svg function, data URIs must be quoted.使用escape-svg函数时，必须引用数据URI。

Add and Subtract functions加减函数

We use the add and subtract functions to wrap the CSS calc function. 我们使用add和substract函数包装CSS calc函数。The primary purpose of these functions is to avoid errors when a “unitless” 0 value is passed into a calc expression. 这些函数的主要目的是避免将“无单位”0值传递到calc表达式时出错。Expressions like calc(10px - 0) will return an error in all browsers, despite being mathematically correct.像calc(10px - 0)这样的表达式在所有浏览器中都会返回一个错误，尽管在数学上是正确的。

Example where the calc is valid:计算有效的示例：

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

Example where the calc is invalid:计算无效的示例：

$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杂合体

Our scss/mixins/ directory has a ton of mixins that power parts of Bootstrap and can also be used across your own project.我们的scss/mixins/目录中有大量的mixin，它们为Bootstrap程序的各个部分提供动力，也可以在您自己的项目中使用。

Color schemes配色方案

A shorthand mixin for the prefers-color-scheme media query is available with support for light, dark, and custom color schemes.prefers-color-scheme媒体查询的速记杂合体可用于支持lignt、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
  }
}