bootstrap-customize

Bootstrap 5.3 自定义

Bootstrap 5.3 通过 Sass 变量、CSS 自定义属性和完整的主题系统（包括内置颜色模式）提供强大的自定义能力。

自定义方法

1. CSS 变量（运行时自定义）

Bootstrap 文档将这些称为“CSS 变量”（严格来说是 CSS 自定义属性）。通过在任意层级覆盖样式，无需重新编译即可修改样式：

/* Global override */
:root {
  --bs-primary: #0074d9;
  --bs-primary-rgb: 0, 116, 217;
  --bs-body-font-family: 'Inter', sans-serif;
}

/* Component-level override */
.my-card {
  --bs-card-bg: #f0f0f0;
  --bs-card-border-color: transparent;
}

/* Local scope override */
.custom-button {
  --bs-btn-bg: #custom-color;
  --bs-btn-border-color: #custom-color;
  --bs-btn-hover-bg: #darker-custom;
}

CSS 变量前缀

通过 $prefix Sass 变量自定义 bs- 前缀，避免在项目中嵌入 Bootstrap 并与其他框架一起使用时发生冲突：

$prefix: "myapp-"; // Results in --myapp-primary, --myapp-body-bg, etc.

2. Sass 变量（编译时）

如需全面自定义主题，请在导入 Bootstrap 之前覆盖 Sass 变量：

// 1. Include functions first
@import "bootstrap/scss/functions";

// 2. Override default variables
$primary: #0074d9;
$secondary: #7fdbff;
$font-family-base: 'Inter', sans-serif;
$border-radius: 0.5rem;
$enable-shadows: true;

// 3. Import Bootstrap
@import "bootstrap/scss/bootstrap";

**顺序很重要：**变量必须在函数之后、其他 Bootstrap 导入之前设置。

颜色系统

主题颜色

八种默认主题颜色，带有 Sass 映射和 CSS 属性：

$theme-colors: (
  "primary":   $primary,
  "secondary": $secondary,
  "success":   $success,
  "info":      $info,
  "warning":   $warning,
  "danger":    $danger,
  "light":     $light,
  "dark":      $dark
);

添加自定义颜色

// Add to theme-colors map
$custom-colors: (
  "custom": #900,
  "brand": #1a73e8
);

// Merge with defaults
$theme-colors: map-merge($theme-colors, $custom-colors);

这会生成所有工具类：.bg-custom、.text-brand、.btn-custom 等。

添加支持深色模式的颜色

仅向 $theme-colors 添加颜色，不会为警告框、徽章和列表组生成正确的深色模式样式。请在其他映射中定义变体：

// Light mode variants
$theme-colors-text: map-merge($theme-colors-text, ("custom": #712cf9));
$theme-colors-bg-subtle: map-merge($theme-colors-bg-subtle, ("custom": #e1d2fe));
$theme-colors-border-subtle: map-merge($theme-colors-border-subtle, ("custom": #bfa1fc));

// Dark mode variants
$theme-colors-text-dark: map-merge($theme-colors-text-dark, ("custom": #e1d2f2));
$theme-colors-bg-subtle-dark: map-merge($theme-colors-bg-subtle-dark, ("custom": #8951fa));
$theme-colors-border-subtle-dark: map-merge($theme-colors-border-subtle-dark, ("custom": #e1d2f2));

如果不添加这些定义，使用 *-text-emphasis、*-bg-subtle 和 *-border-subtle 模式的组件在深色模式下将无法正确显示。

移除颜色

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

警告：primary、success 和 danger 键是必需的，无法移除。Bootstrap 核心样式会将它们用于链接、表单验证和其他组件。移除这些键会导致 Sass 编译错误。

可以安全移除：secondary、info、warning、light、dark

无法移除：primary、success、danger

颜色模式（深色／浅色）

Bootstrap 5.3 内置了深色模式支持。

启用颜色模式

在 <html> 或任意元素上设置 data-bs-theme 属性：

<html lang="en" data-bs-theme="light">


<html lang="en" data-bs-theme="dark">


<div data-bs-theme="dark">
  <div class="card">Dark card in light page</div>
</div>

JavaScript 切换

const toggleTheme = () => {
  const html = document.documentElement;
  const current = html.getAttribute('data-bs-theme');
  html.setAttribute('data-bs-theme', current === 'dark' ? 'light' : 'dark');
};

// With system preference
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
document.documentElement.setAttribute('data-bs-theme',
  prefersDark.matches ? 'dark' : 'light'
);

// Listen for system changes
prefersDark.addEventListener('change', (e) => {
  document.documentElement.setAttribute('data-bs-theme',
    e.matches ? 'dark' : 'light'
  );
});

颜色模式的实现类型

Bootstrap 支持两种颜色模式切换方式，由 $color-mode-type Sass 变量控制。

数据属性方式（默认）

$color-mode-type: data;

使用 HTML 元素上的 data-bs-theme 属性：

<html data-bs-theme="dark">

优点：

• 可以单独控制各个组件的主题
• 用户偏好可以覆盖系统设置
• 支持通过 JavaScript 切换主题
• 支持运行时切换，无需重新加载页面

**适用场景：**构建主题选择器 UI，或需要对各个组件进行精细控制时。

媒体查询方式

$color-mode-type: media-query;

自动使用 prefers-color-scheme 媒体查询：

@media (prefers-color-scheme: dark) {
  /* Dark mode styles applied automatically */
}

优点：

• 自动检测系统偏好
• 无需 JavaScript
• 实现更简单
• 运行时开销为零

缺点：

• 无法单独控制各个组件
• 用户无法通过 UI 覆盖设置
• 仅支持页面级主题设置

**适用场景：**需要自动检测系统偏好，且不需要手动切换时。

自定义颜色模式颜色

除了 light 和 dark，还可以定义完全自定义的颜色模式。有关使用 [data-bs-theme="blue"] 的完整“蓝色主题”示例，请参见 references/sass-variables.md。

按模式覆盖颜色：

// Light mode colors
:root,
[data-bs-theme="light"] {
  --bs-body-bg: #ffffff;
  --bs-body-color: #212529;
}

// Dark mode colors
[data-bs-theme="dark"] {
  --bs-body-bg: #1a1a2e;
  --bs-body-color: #e1e1e1;
  --bs-primary: #6ea8fe;
}

Sass 函数

Bootstrap 提供了用于颜色调整和无障碍设计的实用函数：

• tint-color($color, $weight) - 通过与白色混合来变亮
• shade-color($color, $weight) - 通过与黑色混合来变暗
• shift-color($color, $weight) - 根据权重的正负自动变亮或变暗
• color-contrast($color) - 获取适用于背景的无障碍对比色

// Generate color scale
$primary-light: tint-color($primary, 40%);
$primary-dark: shade-color($primary, 20%);

// Auto-contrast text
.custom-badge {
  background-color: $success;
  color: color-contrast($success); // Returns #fff or #212529
}

// Hover states
.btn-custom:hover {
  background-color: shift-color($brand, 15%);
}

其他函数：用于 SVG 背景的 escape-svg()，以及用于安全 CSS calc 运算的 add()／subtract()。

完整的函数和 mixin 参考请参见 references/sass-functions-mixins.md。

重要 Sass 变量

排版

$font-family-base: system-ui, -apple-system, sans-serif;
$font-family-monospace: SFMono-Regular, Menlo, monospace;
$font-size-base: 1rem;
$font-size-sm: $font-size-base * 0.875;
$font-size-lg: $font-size-base * 1.25;
$font-weight-normal: 400;
$font-weight-bold: 700;
$line-height-base: 1.5;
$headings-font-family: null; // Inherits $font-family-base
$headings-font-weight: 500;

间距

$spacer: 1rem;
$spacers: (
  0: 0,
  1: $spacer * 0.25,  // 0.25rem
  2: $spacer * 0.5,   // 0.5rem
  3: $spacer,         // 1rem
  4: $spacer * 1.5,   // 1.5rem
  5: $spacer * 3      // 3rem
);

边框圆角

$border-radius: 0.375rem;
$border-radius-sm: 0.25rem;
$border-radius-lg: 0.5rem;
$border-radius-xl: 1rem;
$border-radius-xxl: 2rem;
$border-radius-pill: 50rem;

选项标志

$enable-caret: true;
$enable-rounded: true;
$enable-shadows: false;
$enable-gradients: false;
$enable-transitions: true;
$enable-reduced-motion: true;
$enable-smooth-scroll: true;
$enable-grid-classes: true;
$enable-container-classes: true;
$enable-negative-margins: false;
$enable-dark-mode: true;
$color-mode-type: data; // 'data' or 'media-query'

焦点环

Bootstrap 5.3 提供了可用于自定义所有组件 :focus 样式的变量：

$focus-ring-width: .25rem;
$focus-ring-opacity: .25;
$focus-ring-color: rgba($primary, $focus-ring-opacity);
$focus-ring-blur: 0;
$focus-ring-box-shadow: 0 0 $focus-ring-blur $focus-ring-width $focus-ring-color;

组件自定义

按钮自定义

// Global button variables
$btn-padding-y: 0.5rem;
$btn-padding-x: 1rem;
$btn-font-size: 1rem;
$btn-border-radius: $border-radius;

// Per-variant customization via CSS
.btn-primary {
  --bs-btn-bg: #0074d9;
  --bs-btn-border-color: #0074d9;
  --bs-btn-hover-bg: #0063b8;
  --bs-btn-hover-border-color: #005aa3;
  --bs-btn-active-bg: #005aa3;
  --bs-btn-active-border-color: #00518f;
}

卡片自定义

$card-spacer-y: 1rem;
$card-spacer-x: 1rem;
$card-border-width: 1px;
$card-border-radius: $border-radius;
$card-border-color: rgba(0, 0, 0, 0.125);
$card-bg: $white;
$card-cap-bg: rgba(0, 0, 0, 0.03);

表单自定义

$input-padding-y: 0.375rem;
$input-padding-x: 0.75rem;
$input-font-size: 1rem;
$input-border-radius: $border-radius;
$input-border-color: $gray-400;
$input-focus-border-color: tint-color($primary, 50%);
$input-focus-box-shadow: 0 0 0 0.25rem rgba($primary, 0.25);

组件架构

Bootstrap 使用基础类-修饰类模式来设置组件样式。了解这一架构有助于自定义现有组件，并创建能够无缝集成的新组件。

基础类和修饰类

组件从提供核心样式的基础类开始，然后由修饰类添加变体：

<button class="btn">Base button</button>


<button class="btn btn-primary">Primary</button>
<button class="btn btn-lg">Large</button>
<button class="btn btn-primary btn-lg">Primary Large</button>

使用 @each 循环生成变体

Bootstrap 通过遍历 $theme-colors 来生成颜色变体：

// How Bootstrap generates .alert-primary, .alert-danger, etc.
@each $state in map-keys($theme-colors) {
  .alert-#{$state} {
    --#{$prefix}alert-color: var(--#{$prefix}#{$state}-text-emphasis);
    --#{$prefix}alert-bg: var(--#{$prefix}#{$state}-bg-subtle);
    --#{$prefix}alert-border-color: var(--#{$prefix}#{$state}-border-subtle);
  }
}

**关键要点：**向 $theme-colors 添加颜色会自动为警告框、按钮、徽章、列表组等生成变体。

带变体的自定义组件

应用相同模式，以一致的方式创建自定义组件：

// Base class
.callout {
  padding: var(--bs-callout-padding, 1rem);
  border-left: 4px solid var(--bs-callout-border-color, currentcolor);
  background: var(--bs-callout-bg, transparent);
}

// Generate variants from theme colors
@each $state, $value in $theme-colors {
  .callout-#{$state} {
    --bs-callout-border-color: var(--bs-#{$state});
    --bs-callout-bg: var(--bs-#{$state}-bg-subtle);
  }
}

这会生成 .callout-primary、.callout-danger 等，它们都会继承基础 .callout 样式。

有关遵循此模式的 button-variant() 和其他混入，请参阅 references/sass-functions-mixins.md。

创建自定义组件

使用 Bootstrap 的混入和函数创建样式一致的组件：

.custom-component {
  // Use Bootstrap's spacing
  padding: map-get($spacers, 3);
  margin-bottom: map-get($spacers, 4);

  // Use Bootstrap's colors
  background-color: var(--bs-body-bg);
  color: var(--bs-body-color);
  border: 1px solid var(--bs-border-color);
  border-radius: var(--bs-border-radius);

  // Use Bootstrap's shadows
  @if $enable-shadows {
    box-shadow: $box-shadow-sm;
  }

  // Responsive behavior
  @include media-breakpoint-up(md) {
    padding: map-get($spacers, 4);
  }
}

优化

Bootstrap 的完整包体积较大。使用以下策略来减小生产环境的包体积。

精简 Sass 导入

仅导入所用的组件：

// Required core
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/root";

// Optional - import only what you use
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/containers";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/buttons";

完整的最小化构建示例请参阅 examples/selective-imports.scss。

精简 JavaScript 导入

通过导入单个插件，对 Bootstrap JavaScript 进行摇树优化：

// Instead of importing everything
// import * as bootstrap from 'bootstrap';

// Import only what you need
import Modal from 'bootstrap/js/dist/modal';
import Dropdown from 'bootstrap/js/dist/dropdown';
import Collapse from 'bootstrap/js/dist/collapse';

// Initialize manually
const modal = new Modal('#myModal');

注意：某些插件存在依赖项（例如，Dropdown 需要 Popper.js）。请查看插件文档。

使用 PurgeCSS 移除未使用的 CSS

PurgeCSS 会从生产构建中移除未使用的样式：

// postcss.config.js
module.exports = {
  plugins: [
    require('@fullhuman/postcss-purgecss')({
      content: ['./src/**/*.html', './src/**/*.js'],
      // Safelist Bootstrap's dynamic classes
      safelist: {
        standard: [/^modal/, /^show/, /^fade/, /^collapse/, /^offcanvas/],
        deep: [/^tooltip/, /^popover/, /^bs-/]
      }
    })
  ]
}

Bootstrap 会动态添加 show、fade、collapsing 等类。务必将这些模式加入安全列表。

Autoprefixer 配置

配置浏览器支持范围，以避免不必要的供应商前缀：

# .browserslistrc
>= 0.5%
last 2 major versions
not dead
not Explorer <= 11

这是 Bootstrap 的默认配置。请根据受众进行调整。

生产环境最佳实践

**压缩：**在生产环境中使用压缩后的发行文件：

• bootstrap.min.css（而非 bootstrap.css）
• bootstrap.bundle.min.js（而非 bootstrap.bundle.js）

**压缩传输：**在服务器上启用 gzip 或 Brotli：

# nginx.conf
gzip on;
gzip_types text/css application/javascript;

**非阻塞加载：**对非关键脚本使用 defer：

<link rel="stylesheet" href="bootstrap.min.css">


<script src="bootstrap.bundle.min.js" defer></script>

**HTTPS：**始终通过 HTTPS 提供 Bootstrap。CDN 链接需要安全连接，现代浏览器可能会阻止混合内容。

安全注意事项

内容安全策略（CSP）

Bootstrap 在 CSS 中使用内嵌 SVG（data: URI），以确保跨浏览器样式一致。如果应用采用严格的内容安全策略，某些组件可能无法正确显示。

受影响的组件：

• Accordion（折叠/展开图标）
• Carousel（上一个/下一个控件）
• Close button（X 图标）
• Form controls（复选框、单选按钮、开关、验证图标）
• Navbar toggle（汉堡图标）
• Select menus（下拉箭头）

CSP 冲突的表现：

• 表单复选框不显示勾选标记
• Accordion 缺少展开/折叠图标
• Navbar 汉堡菜单显示异常
• Select 下拉菜单缺少箭头

解决方案：

1. 替换为本地资源——使用 escape-svg() 函数和托管在本地的 SVG 文件：

// Custom checkbox with local SVG instead of data: URI
$form-check-input-checked-bg-image: url("/assets/icons/check.svg");

2. 调整 CSP——如果符合安全要求，可在策略中允许内嵌 SVG data URI

3. 使用 Bootstrap Icons 字体——将 SVG 图标替换为 Bootstrap Icons 字体变体

对于采用严格 CSP 的环境，请在规划自定义方案时审查 Bootstrap 对 SVG 的使用情况。

参阅：Bootstrap CSP 文档

其他资源

参考文件

• references/sass-variables.md - 完整的 Sass 变量参考
• references/sass-functions-mixins.md - 完整的函数和混入参考

示例文件

• examples/color-mode-toggle.html - 完整的深色／浅色模式切换示例，并检测系统偏好设置
• examples/custom-theme-demo.html - 无需 Sass 编译即可在运行时使用 CSS 变量设置主题