在 GitHub 上查看

Bootstrap 主题

使用我们新的内置 Sass 变量自定义 Bootstrap 4,以实现全局样式偏好设置,从而轻松进行主题设置和组件更改。

简介

在 Bootstrap 3 中,主题设置主要由 LESS 中的变量覆盖、自定义 CSS 和我们在 dist 文件中包含的单独主题样式表驱动。通过一些努力,人们可以在不触及核心文件的情况下完全重新设计 Bootstrap 3 的外观。Bootstrap 4 提供了一种熟悉但略有不同的方法。

现在,主题设置通过 Sass 变量、Sass 映射和自定义 CSS 来完成。不再有专门的主题样式表;相反,你可以启用内置主题以添加渐变、阴影等。

Sass

使用我们的源 Sass 文件利用变量、映射、混合等,在使用你自己的资产管道编译 Sass时。

文件结构

尽可能避免修改 Bootstrap 的核心文件。对于 Sass,这意味着创建你自己的样式表,它导入 Bootstrap,以便你可以修改和扩展它。假设你正在使用 npm 这样的包管理器,你将拥有如下所示的文件结构

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

如果你已下载我们的源文件,并且没有使用包管理器,则需要手动设置类似于该结构的内容,将 Bootstrap 的源文件与你自己的文件分开。

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

导入

在你的 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
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";

// 4. Include any optional Bootstrap components as you like
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/code";
@import "../node_modules/bootstrap/scss/grid";

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

变量默认值

Bootstrap 中的每个 Sass 变量都包含 !default 标志,允许你在自己的 Sass 中覆盖变量的默认值,而无需修改 Bootstrap 的源代码。根据需要复制并粘贴变量,修改其值,并删除 !default 标志。如果变量已分配,则不会被 Bootstrap 中的默认值重新分配。

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

变量覆盖必须在导入我们的函数、变量和混合后,但在导入其余部分之前。

以下是一个示例,它通过 npm 导入和编译 Bootstrap 时更改 <body>background-colorcolor

@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";

// Optional Bootstrap components here
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

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

使用我们的 starter 项目通过 npm 开始使用 Bootstrap!前往 twbs/bootstrap-npm-starter 模板存储库,了解如何在自己的 npm 项目中构建和自定义 Bootstrap。包括 Sass 编译器、Autoprefixer、Stylelint、PurgeCSS 和 Bootstrap 图标。

映射和循环

Bootstrap 4 包含一些 Sass 映射,键值对使生成相关 CSS 系列变得更加容易。我们为颜色、网格断点等使用 Sass 映射。与 Sass 变量一样,所有 Sass 映射都包含 !default 标志,并且可以被覆盖和扩展。

默认情况下,我们的某些 Sass 映射被合并到空映射中。这样做是为了允许轻松扩展给定的 Sass 映射,但代价是使从映射中删除项目变得稍微困难一些。

修改映射

若要修改我们的 $theme-colors 映射中的现有颜色,请将以下内容添加到你的自定义 Sass 文件

$theme-colors: (
  "primary": #0074d9,
  "danger": #ff4136
);

添加到映射

若要向 $theme-colors 添加新颜色,请添加新键和值

$theme-colors: (
  "custom-color": #900
);

从映射中移除

要从 $theme-colors 或任何其他映射中删除颜色,请使用 map-remove。请注意,你必须将它插入到我们的要求和选项之间

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

// Optional
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
...

必需键

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

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

函数

Bootstrap 利用了多个 Sass 函数,但只有一部分适用于常规主题。我们包含了三个函数,用于从颜色映射中获取值

@function color($key: "blue") {
  @return map-get($colors, $key);
}

@function theme-color($key: "primary") {
  @return map-get($theme-colors, $key);
}

@function gray($key: "100") {
  @return map-get($grays, $key);
}

这些函数允许你从 Sass 映射中选择一种颜色,就像你使用 v3 中的颜色变量一样。

.custom-element {
  color: gray("100");
  background-color: theme-color("dark");
}

我们还有另一个函数,用于从 $theme-colors 映射中获取特定级别的颜色。负级别值会使颜色变浅,而较高级别会使颜色变深。

@function theme-color-level($color-name: "primary", $level: 0) {
  $color: theme-color($color-name);
  $color-base: if($level > 0, #000, #fff);
  $level: abs($level);

  @return mix($color-base, $color, $level * $theme-color-interval);
}

在实践中,你将调用该函数并传入两个参数:$theme-colors 中颜色的名称(例如,primary 或 danger)和一个数字级别。

.custom-element {
  color: theme-color-level(primary, -10);
}

将来可以在你自己的自定义 Sass 中添加其他函数,为其他 Sass 映射创建级别函数,甚至如果你想更详细,也可以创建一个通用函数。

颜色对比度

我们在 Bootstrap 中包含的另一个函数是颜色对比函数 color-yiq。它利用YIQ 色彩空间根据指定的基色自动返回浅色 (#fff) 或深色 (#111) 对比色。此函数对于生成多个类的混合或循环特别有用。

例如,要从我们的 $theme-colors 映射生成颜色样本

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

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

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

你还可以使用我们的颜色映射函数指定基色

.custom-element {
  color: color-yiq(theme-color("dark")); // returns `color: #fff`
}

转义 SVG

我们使用 escape-svg 函数来转义 SVG 背景图像的 <># 字符。需要转义这些字符才能在 IE 中正确呈现背景图像。使用 escape-svg 函数时,必须引用数据 URI。

加法和减法函数

我们使用 addsubtract 函数来包装 CSS calc 函数。这些函数的主要目的是避免在将“无单位”0 值传递到 calc 表达式时出现错误。诸如 calc(10px - 0) 之类的表达式在所有浏览器中都会返回错误,尽管在数学上是正确的。

calc 有效的示例

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

calc 无效的示例

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

Sass 选项

使用我们内置的自定义变量文件来自定义 Bootstrap 4,并使用新的 $enable-* Sass 变量轻松切换全局 CSS 偏好设置。根据需要覆盖变量的值并使用 npm run test 重新编译。

您可以在 Bootstrap 的 scss/_variables.scss 文件中查找和自定义这些变量,以获取关键全局选项。

变量 说明
$spacer 1rem(默认值)或任何大于 0 的值 指定默认间隔值以通过编程生成我们的间隔实用程序
$enable-rounded true(默认值)或 false 在各种组件上启用预定义的 border-radius 样式。
$enable-shadows truefalse(默认值) 在各种组件上启用预定义的装饰性 box-shadow 样式。不影响用于焦点状态的 box-shadow
$enable-gradients truefalse(默认值) 在各种组件上通过 background-image 样式启用预定义的渐变。
$enable-transitions true(默认值)或 false 在各种组件上启用预定义的 transition
$enable-prefers-reduced-motion-media-query true(默认值)或 false 启用prefers-reduced-motion 媒体查询,它会根据用户的浏览器/操作系统偏好设置抑制某些动画/过渡。
$enable-hover-media-query truefalse(默认值) 已弃用
$enable-grid-classes true(默认值)或 false 启用为网格系统生成 CSS 类(例如,.container.row.col-md-1 等)。
$enable-caret true(默认值)或 false .dropdown-toggle 上启用伪元素插入符号。
$enable-pointer-cursor-for-buttons true(默认值)或 false 向未禁用的按钮元素添加“手”光标。
$enable-print-styles true(默认值)或 false 启用优化打印的样式。
$enable-responsive-font-sizes truefalse(默认值) 启用响应式字体大小
$enable-validation-icons true(默认值)或 false 在文本输入和一些自定义表单中启用用于验证状态的 background-image 图标。
$enable-deprecation-messages true(默认值)或 false 设置为 false 以在使用计划在 v5 中删除的任何已弃用的混合和函数时隐藏警告。

颜色

Bootstrap 的许多组件和实用程序都是通过 Sass 映射中定义的一系列颜色构建的。可以在 Sass 中循环使用此映射以快速生成一系列规则集。

所有颜色

Bootstrap 4 中的所有颜色都可用作 Sass 变量和 scss/_variables.scss 文件中的 Sass 映射。这将在后续小版本中扩展,以添加更多色调,就像我们已经包含的 灰度调色板 一样。

$blue #007bff
$indigo #6610f2
$purple #6f42c1
$pink #e83e8c
$red #dc3545
$orange #fd7e14
$yellow #ffc107
$green #28a745
$teal #20c997
$cyan #17a2b8

以下是如何在 Sass 中使用它们

// With variable
.alpha { color: $purple; }

// From the Sass map with our `color()` function
.beta { color: color("purple"); }

颜色实用程序类也可用于设置 colorbackground-color

将来,我们旨在为每种颜色的色调提供 Sass 映射和变量,就像我们在下面的灰度颜色中所做的那样。

主题颜色

我们使用所有颜色的子集来创建较小的调色板以生成配色方案,也可以在 Bootstrap 的 scss/_variables.scss 文件中作为 Sass 变量和 Sass 映射使用。

$primary #007bff
$secondary #6c757d
$success #28a745
$danger #dc3545
$warning #ffc107
$info #17a2b8
$light #f8f9fa
$dark #343a40

灰色

scss/_variables.scss 中的一组扩展的灰色变量和 Sass 映射,用于在整个项目中保持一致的灰色色调。请注意,这些是“冷灰色”,它们倾向于微妙的蓝色调,而不是中性灰色。

$gray-100 #f8f9fa
$gray-200 #e9ecef
$gray-300 #dee2e6
$gray-400 #ced4da
$gray-500 #adb5bd
$gray-600 #6c757d
$gray-700 #495057
$gray-800 #343a40
$gray-900 #212529

scss/_variables.scss 中,您将找到 Bootstrap 的颜色变量和 Sass 映射。以下是 $colors Sass 映射的一个示例

$colors: (
  "blue": $blue,
  "indigo": $indigo,
  "purple": $purple,
  "pink": $pink,
  "red": $red,
  "orange": $orange,
  "yellow": $yellow,
  "green": $green,
  "teal": $teal,
  "cyan": $cyan,
  "white": $white,
  "gray": $gray-600,
  "gray-dark": $gray-800
) !default;

在映射中添加、删除或修改值,以更新它们在许多其他组件中使用的方式。遗憾的是,目前并非所有组件都利用此 Sass 映射。未来的更新将努力改进这一点。在此之前,计划使用 ${color} 变量和此 Sass 映射。

组件

Bootstrap 的许多组件和实用程序都是使用 @each 循环构建的,这些循环会遍历 Sass 映射。这对于通过我们的 $theme-colors 生成组件的变体和为每个断点创建响应式变体特别有用。在您自定义这些 Sass 映射并重新编译时,您将自动看到这些循环中反映您的更改。

修饰符

Bootstrap 的许多组件都是使用基本修饰符类方法构建的。这意味着大部分样式都包含在一个基本类中(例如,.btn),而样式变体则限制在修饰符类中(例如,.btn-danger)。这些修饰符类是根据 $theme-colors 映射构建的,以便自定义我们的修饰符类的数量和名称。

以下是我们如何循环遍历 $theme-colors 映射以生成 .alert 组件和我们所有 .bg-* 背景实用程序的修饰符的两个示例。

// Generate alert modifier classes
@each $color, $value in $theme-colors {
  .alert-#{$color} {
    @include alert-variant(theme-color-level($color, -10), theme-color-level($color, -9), theme-color-level($color, 6));
  }
}

// Generate `.bg-*` color utilities
@each $color, $value in $theme-colors {
  @include bg-variant('.bg-#{$color}', $value);
}

响应式

这些 Sass 循环也不限于颜色映射。您还可以生成组件或实用程序的响应式变体。以我们的响应式文本对齐实用程序为例,我们在其中将 $grid-breakpoints Sass 映射的 @each 循环与媒体查询 include 混合使用。

@each $breakpoint in map-keys($grid-breakpoints) {
  @include media-breakpoint-up($breakpoint) {
    $infix: breakpoint-infix($breakpoint, $grid-breakpoints);

    .text#{$infix}-left   { text-align: left !important; }
    .text#{$infix}-right  { text-align: right !important; }
    .text#{$infix}-center { text-align: center !important; }
  }
}

如果您需要修改 $grid-breakpoints,您的更改将应用于遍历该映射的所有循环。

CSS 变量

Bootstrap 4 在其编译的 CSS 中包含大约二十几个 CSS 自定义属性(变量)。在浏览器的检查器、代码沙箱或一般原型设计中工作时,这些属性提供了对常用值(如我们的主题颜色、断点和主要字体堆栈)的轻松访问。

可用变量

以下是我们包含的变量(请注意,:root 是必需的)。它们位于我们的 _root.scss 文件中。

:root {
  --blue: #007bff;
  --indigo: #6610f2;
  --purple: #6f42c1;
  --pink: #e83e8c;
  --red: #dc3545;
  --orange: #fd7e14;
  --yellow: #ffc107;
  --green: #28a745;
  --teal: #20c997;
  --cyan: #17a2b8;
  --white: #fff;
  --gray: #6c757d;
  --gray-dark: #343a40;
  --primary: #007bff;
  --secondary: #6c757d;
  --success: #28a745;
  --info: #17a2b8;
  --warning: #ffc107;
  --danger: #dc3545;
  --light: #f8f9fa;
  --dark: #343a40;
  --breakpoint-xs: 0;
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 992px;
  --breakpoint-xl: 1200px;
  --font-family-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --font-family-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}

示例

CSS 变量提供了与 Sass 变量类似的灵活性,但无需在提供给浏览器之前进行编译。例如,这里我们正在使用 CSS 变量重置我们页面的字体和链接样式。

body {
  font: 1rem/1.5 var(--font-family-sans-serif);
}
a {
  color: var(--blue);
}

断点变量

虽然我们最初在 CSS 变量中包含断点(例如,--breakpoint-md),但媒体查询不支持这些断点,但它们仍然可以在媒体查询中的规则集中使用。鉴于 JavaScript 可以利用这些断点变量,因此它们保留在已编译的 CSS 中以实现向后兼容性。在规范中了解更多信息

以下是不受支持的内容示例:

@media (min-width: var(--breakpoint-sm)) {
  ...
}

以下是受支持的内容示例:

@media (min-width: 768px) {
  .custom-element {
    color: var(--primary);
  }
}