颜色模式 · Bootstrap 6.0 中文文档

自己试一试！ 下载使用 Bootstrap 与 Stylelint 的源代码和工作演示，以及 twbs/examples 仓库中的颜色模式。

深色模式

Bootstrap 原生支持浅色和深色模式。 它们基于原生 CSS 的 light-dark() 函数和 color-scheme 属性构建，因此我们的颜色标记会自动解析为浅色或深色值——无需重新编译，也无需重复的样式表。

这为你提供了两全其美的体验，无需设置任何标志：

系统默认偏好。 我们的 :root 被声明为 color-scheme: light dark，因此页面会自动跟随访问者的操作系统偏好（prefers-color-scheme），就像媒体查询的实现一样。
使用数据属性覆盖。 设置 data-bs-theme="light" 或 data-bs-theme="dark" 在……上 <html> 元素用于强制整个页面的模式，或用于任何元素或组件，将模式仅限制在该子树范围内。

你不必在媒体查询和数据属性之间做选择——因为颜色模式由color-scheme驱动，系统偏好和任何data-bs-theme覆盖可以一起工作。

示例

例如，要更改菜单的颜色模式，请在父元素中添加data-bs-theme="light"或data-bs-theme="dark"。现在，无论全局颜色模式如何，这些菜单都会显示指定的主题值。

HTML

<div data-bs-theme="light">
  <button class="btn-solid theme-secondary" type="button" data-bs-toggle="menu" aria-expanded="false">
    Default menu
  </button>
  <div class="menu">
    <a class="menu-item active" href="#">Action</a>
    <a class="menu-item" href="#">Action</a>
    <a class="menu-item" href="#">Another action</a>
    <a class="menu-item" href="#">Something else here</a>
    <hr class="menu-divider">
    <a class="menu-item" href="#">Separated link</a>
  </div>
</div>

<div data-bs-theme="dark">
  <button class="btn-solid theme-secondary" type="button" data-bs-toggle="menu" aria-expanded="false">
    Dark menu
  </button>
  <div class="menu">
    <a class="menu-item active" href="#">Action</a>
    <a class="menu-item" href="#">Action</a>
    <a class="menu-item" href="#">Another action</a>
    <a class="menu-item" href="#">Something else here</a>
    <hr class="menu-divider">
    <a class="menu-item" href="#">Separated link</a>
  </div>
</div>

它是如何工作的

我们的颜色标记在一次中定义 :root 使用 CSS light-dark() 函数，例如 --bs-border-color: light-dark(var(--bs-gray-200), var(--bs-gray-700))每个令牌都包含其明亮和暗淡的值，浏览器会根据元素使用的配色方案选择正确的值。
这 :root 元素被设置为 color-scheme: light dark，因此该页面默认会尊重访问者的系统偏好。对于自动暗模式，无需其他设置。
这 data-bs-theme 属性重写 color-scheme 针对其设置的元素及其子孙元素——[data-bs-theme="dark"] 集合 color-scheme: dark 和 [data-bs-theme="light"] 集合 color-scheme: light. 那迫使每一个 light-dark() 该子树中的令牌将解析为所选择的模式，这就是为什么你可以从翻转整页 <html> 或者只重新着色单个组件（如上所示）。
对于无法以令牌表示的样式——自定义组件或你自己的额外颜色模式——请使用 color-mode() Sass mixin，用于将规则限定到某个模式。见使用 Sass 构建.

用法

启用暗黑模式

默认情况下，Bootstrap 已经遵循访客的系统偏好，因此你无需做任何事情即可获得自动暗模式。力量无论其系统设置如何，都启用暗模式，添加 data-bs-theme="dark" 归因于 <html> 元素。这会将深色模式应用于所有组件和元素，除了那些具有自身设置的元素 data-bs-theme 属性。基于快速启动模板:

HTML

          <!doctype html>
<html lang="en" data-bs-theme="dark">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap demo</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@6.0.0-alpha.1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-B/GM4XqrwHnWXNOWMbloTmrYXZg10cakYGmpfsR/bbzQ6JAJI4ihuyADKLnBgrCe" crossorigin="anonymous">
  </head>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="https://cdn.jsdelivr.net/npm/bootstrap@6.0.0-alpha.1/dist/js/bootstrap.bundle.min.js" integrity="sha384-1a/pXj49ZQ1aHEmrJ+gMw1otqoVsYwlEnlD8mIfY2TV03r20Y0CN7uqx1tQogjPL" crossorigin="anonymous"></script>
  </body>
</html>

Bootstrap 还没有自带内置的颜色模式选择器，但如果你愿意，可以使用我们自己文档中的版本。在 JavaScript 部分了解更多。

使用 Sass 构建

我们内置的亮色和暗色令牌可以通过 light-dark() 自动切换，因此你不需要使用 Sass 就能实现自动暗模式。color-mode() mixin 用于额外的情况：无法通过令牌捕获的样式，或你自己的额外自定义颜色模式。

这个混入可以通过两种方式输出其规则，由 $color-mode-type Sass 变量控制：

media-query（默认）将你的样式包装在@media (prefers-color-scheme: …)块中，因此它们会遵循系统偏好。
data将你的样式范围限定在[data-bs-theme="…"]选择器内，因此它们可以按页面或按组件切换。

例如，选择使用data属性方法会生成一个作用域选择器：

SCSS

          $color-mode-type: data;

@include color-mode(dark) {
  .element {
    color: var(--bs-primary-fg-emphasis);
    background-color: var(--bs-primary-bg-subtle);
  }
}

输出到：

CSS

          [data-bs-theme=dark] .element {
  color: var(--bs-primary-fg-emphasis);
  background-color: var(--bs-primary-bg-subtle);
}

使用默认的 media-query 类型时，相同的 mixin 输出会被包装在媒体查询中：

SCSS

          $color-mode-type: media-query;

@include color-mode(dark) {
  .element {
    color: var(--bs-primary-fg-emphasis);
    background-color: var(--bs-primary-bg-subtle);
  }
}

输出到：

CSS

          @media (prefers-color-scheme: dark) {
  .element {
    color: var(--bs-primary-fg-emphasis);
    background-color: var(--bs-primary-bg-subtle);
  }
}

自定义颜色模式

虽然颜色模式的主要用例是亮色模式和暗色模式，但自定义颜色模式也是可能的。创建一个带有自定义值作为颜色模式名称的data-bs-theme选择器，然后根据需要修改我们的 Sass 和 CSS 变量。Bootstrap 内置的暗色模式使用 _root.scss 和 _theme.scss，但你可以在自己的样式表中遵循相同的模式。

例如，你可以使用选择器data-bs-theme="blue"创建一个“蓝色主题”。在你的自定义 Sass 或 CSS 文件中，添加新的选择器并根据需要覆盖任何全局或组件 CSS 变量。如果你使用的是 Sass，你还可以在 CSS 变量覆盖中使用 Sass 的函数。

site/src/scss/_content.scss

[data-bs-theme="blue"] {
  --bs-fg-body: var(--bs-white);
  --bs-bg-body: var(--bs-blue-500);
  --bs-bg-3: var(--bs-blue-600);
  --bs-hr-border-color: var(--bs-blue-400);

  .menu {
    --bs-menu-bg: color-mix(in lab, var(--bs-blue-600), var(--bs-blue-700));
    --bs-menu-item-hover-bg: var(--bs-blue-700);
    --bs-menu-item-active-bg: var(--bs-blue-800);
  }

  .btn-solid {
    --bs-btn-bg: color-mix(in lab, var(--bs-gray-600), var(--bs-blue-400));
    --bs-btn-border-color: color-mix(in lab, var(--bs-fg-body) 25%, transparent);
    --bs-btn-hover-bg: color-mix(in lab, var(--bs-gray-600), var(--bs-blue-400));
    --bs-btn-hover-border-color: color-mix(in lab, var(--bs-fg-body) 25%, transparent);
    --bs-btn-active-bg: color-mix(in lab, color-mix(in lab, var(--bs-gray-600), var(--bs-blue-400)), var(--bs-black) 10%);
    --bs-btn-active-border-color: color-mix(in lab, var(--bs-fg-body), transparent);
    --bs-btn-focus-border-color: color-mix(in lab, var(--bs-fg-body), transparent);
    --bs-btn-focus-box-shadow: 0 0 0 .25rem rgb(255 255 255 / .2);
  }
}

蓝色主题示例

一些段落文本，用于展示蓝色主题在书面内容中的效果。

HTML

          <div data-bs-theme="blue">
  ...
</div>

JavaScript

为了允许访问者或用户切换颜色模式，你需要创建一个切换元素来控制根元素上的data-bs-theme属性，<html>。我们在文档中构建了一个切换器，它最初遵循用户当前的系统颜色模式，但提供一个选项来覆盖该设置并选择特定的颜色模式。

这里展示了驱动它的 JavaScript。欢迎查看我们自己的文档导航栏，了解它是如何使用我们自有组件的 HTML 和 CSS 实现的。建议将 JavaScript 放在页面顶部，以减少网站重新加载时可能出现的屏幕闪烁。请注意，如果你决定为颜色模式使用媒体查询，如果希望使用隐式控制，可能需要修改或移除你的 JavaScript。

JavaScript

/*!
 * Color mode toggler for Bootstrap's docs (https://bs.88fc.cn/)
 * Copyright 2011-2026 The Bootstrap Authors
 * Licensed under the Creative Commons Attribution 3.0 Unported License.
 */

(() => {
  'use strict'

  const getStoredTheme = () => localStorage.getItem('theme')
  const setStoredTheme = theme => localStorage.setItem('theme', theme)

  const getPreferredTheme = () => {
    const storedTheme = getStoredTheme()
    if (storedTheme) {
      return storedTheme
    }

    return 'auto'
  }

  const resolveTheme = theme => {
    if (theme === 'auto') {
      return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
    }

    return theme
  }

  const setTheme = theme => {
    const resolved = resolveTheme(theme)

    if (document.documentElement.getAttribute('data-bs-theme') !== resolved) {
      document.documentElement.setAttribute('data-bs-theme', resolved)
    }
  }

  setTheme(getPreferredTheme())

  const showActiveTheme = (theme, focus = false) => {
    const themeSwitcher = document.querySelector('#bd-theme')

    if (!themeSwitcher) {
      return
    }

    const activeThemeIcon = document.querySelector('.theme-icon-active use')
    const btnToActive = document.querySelector(`[data-bs-theme-value="${theme}"]`)
    const svgOfActiveBtn = btnToActive.querySelector('svg use').getAttribute('href')

    document.querySelectorAll('[data-bs-theme-value]').forEach(element => {
      element.classList.remove('active')
      element.setAttribute('aria-pressed', 'false')
    })

    btnToActive.classList.add('active')
    btnToActive.setAttribute('aria-pressed', 'true')
    activeThemeIcon.setAttribute('href', svgOfActiveBtn)
    themeSwitcher.setAttribute('aria-label', `Toggle theme (${btnToActive.dataset.bsThemeValue})`)

    if (focus) {
      themeSwitcher.focus()
    }
  }

  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
    const storedTheme = getStoredTheme()
    if (storedTheme !== 'light' && storedTheme !== 'dark') {
      setTheme(getPreferredTheme())
    }
  })

  window.addEventListener('DOMContentLoaded', () => {
    showActiveTheme(getPreferredTheme())

    document.querySelectorAll('[data-bs-theme-value]')
      .forEach(toggle => {
        toggle.addEventListener('click', () => {
          const theme = toggle.getAttribute('data-bs-theme-value')
          setStoredTheme(theme)

          requestAnimationFrame(() => {
            setTheme(theme)
            showActiveTheme(theme)
          })
        })
      })
  })
})()

CSS

变量

几十个根级 CSS 变量通过 light-dark() 拥有亮色和暗色值，因此单个 :root 声明即可覆盖两种模式——无需重复暗模式覆盖。在为你自己的自定义颜色模式定义变量时，请以此作为指导。

Sass 变量

我们的浅色和深色颜色标记是由 Sass 在 _root.scss 和 _theme.scss 中生成的，其中大多数以 light-dark() 值输出，因此它们会自动解析。通过 CSS 遮罩绘制其图标的组件（轮播控件、关闭按钮等）会继承当前颜色，并在无需每种模式覆盖的情况下适应活动模式。

Sass 混入

深色模式的样式，以及你创建的任何自定义颜色模式，都可以适当地限定到 data-bs-theme 带可自定义的属性选择器或媒体查询 color-mode() 混入。参见 Sass 使用部分欲了解更多详情。

scss/mixins/_color-mode.scss

@mixin color-mode($mode: light, $root: false) {
  @if $color-mode-type == "media-query" {
    @if $root == true {
      @media (prefers-color-scheme: $mode) {
        :root,
        :host {
          @content;
        }
      }
    } @else {
      @media (prefers-color-scheme: $mode) {
        @content;
      }
    }
  } @else {
    [data-bs-theme="#{$mode}"] {
      @content;
    }
  }
}