Bootstrap V5.3 : Sass 定制化的核心中文翻译版

利用我们的源 Sass 文件来利用变量、映射、混合和函数来帮助您更快地构建和自定义您的项目。

利用我们的源 Sass 文件来利用变量、映射、混合等。

使用最新版本的 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

进口

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

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

设置到位后，您可以开始修改 .您还可以根据需要开始在该部分下添加 Bootstrap 的各个部分。我们建议使用我们文件中的完整导入堆栈作为您的起点。custom.scss// Optionalbootstrap.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

在 VS Code sass-lang.com/install 和编译中详细了解选项。

将 Bootstrap 与其他构建工具一起使用？考虑阅读我们的 Webpack、Parcel 或 Vite 编译指南。我们在 GitHub 上的示例存储库中也有生产就绪的演示。

包括

编译 CSS 后，您可以将其包含在 HTML 文件中。在中，您需要包含编译后的 CSS 文件。如果您更改了已编译的 CSS 文件的路径，请务必更新它。index.html

<!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 变量都包含该标志，允许您在自己的 Sass 中覆盖变量的默认值，而无需修改 Bootstrap 的源代码。根据需要复制和粘贴变量，修改其值，并删除标志。如果已经分配了变量，则不会通过 Bootstrap 中的默认值重新分配该变量。!default!default

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

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

这是一个示例，当通过 npm 导入和编译 Bootstrap 时，它更改了和：background-colorcolor<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 图标。

地图和循环

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

默认情况下，我们的一些 Sass 地图被合并为空地图。这样做是为了允许轻松扩展给定的 Sass 地图，但代价是使从地图中删除物品变得更加困难。

修改地图

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

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

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

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

添加到地图

通过使用自定义值创建新的 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);

从地图中删除

要从或任何其他贴图中删除颜色，请使用。请注意，您必须在我们的要求之间插入其定义之后和之前：$theme-colorsmap-remove$theme-colorsvariablesmaps

// 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 地图的键时遇到错误。

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

功能

颜色

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

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

您可以使用 Bootstrap 和函数使颜色变亮或变暗。这些功能将颜色与黑色或白色混合，这与 Sass 的原生功能不同，这些功能会以固定量改变亮度，这通常不会产生预期的效果。tint-color()shade-color()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%);
}

颜色对比度

为了满足 Web 内容辅助功能指南（WCAG）对比度要求，作者必须提供 4.5：1 的最小文本颜色对比度和 3：1 的最小非文本颜色对比度，只有极少数例外。

为了帮助解决这个问题，我们在 Bootstrap 中包含了该函数。它使用 WCAG 对比度算法根据色彩空间中的相对亮度计算对比度阈值，以根据指定的基色自动返回浅色（）、深色（）或黑色（）对比度颜色。此函数对于生成多个类的混合或循环特别有用。color-contrastsRGB#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

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

加减函数

我们使用 and 函数来包装 CSS 函数。这些函数的主要目的是避免在将“无单位”值传递到表达式时出错。像这样的表达式将在所有浏览器中返回错误，尽管在数学上是正确的。addsubtractcalc0calccalc(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，它们为 Bootstrap 的各个部分提供支持，也可以在您自己的项目中使用。scss/mixins/

配色方案

媒体查询的简写混合可用，支持和配色方案。有关颜色模式混合的信息，请参阅颜色模式文档。prefers-color-schemelightdark

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

入门指南 Getting started

定制化 Customize

布局方式 Layout

内容样式 Content

表单控件 Forms

组件集合 Components

辅助工具 Helpers

工具类库 Utilities

功能扩展 Extend

关于Bootstrap

Sass 定制化的核心