颜色模式

从 v5.3.0 开始，Bootstrap 现在支持颜色模式或主题。探索我们的默认浅色模式和新的深色模式，或使用我们的样式作为模板创建您自己的模式。

在本页

深色模式

Bootstrap 现在支持颜色模式，从深色模式开始！使用 v5.3.0，您可以实现自己的颜色模式切换器（请参阅下面的 Bootstrap 文档中的示例）并应用您认为合适的不同颜色模式。我们支持亮模式（默认）和暗模式。借助data-bs-theme属性，可以在<html>元素或特定组件和元素上全局切换颜色模式。

或者，通过我们的颜色模式混合，您也可以切换到媒体查询实现——详情请参阅使用部分。不过请注意——这会消除您在每个组件的基础上更改主题的能力，如下所示。

例子

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

HTML

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

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

怎么运行的

如上所示，颜色模式样式由data-bs-theme属性控制。此属性可应用于<html>元素，或任何其他元素或 Bootstrap 组件。如果应用于<html>元素，它将应用于所有内容。如果应用于组件或元素，它将限定在该特定组件或元素内。
对于您希望支持的每种颜色模式，您需要为共享的全局 CSS 变量添加新的覆盖。我们已经在_root.scss深色模式的样式表中这样做了，浅色模式是默认值。在编写颜色模式特定样式时，使用 mixin：
```
// Color mode variables in _root.scss
@include color-mode(dark) {
  // CSS variable overrides here...
}
```
我们使用自定义_variables-dark.scss来为暗模式提供那些共享的全局 CSS 变量覆盖。您自己的自定义颜色模式不需要此文件，但出于两个原因，我们的深色模式需要此文件。首先，最好有一个地方来重置全局颜色。其次，对于嵌入在手风琴、表单组件等的 CSS 中的背景图像，必须覆盖一些 Sass 变量。

嵌套颜色模式

在嵌套元素上使用data-bs-theme以更改一组元素或组件的颜色模式。在下面的示例中，我们有一个带有嵌套光模式的外部暗模式。您会注意到组件自然地调整了它们的外观，但您可能需要在此过程中添加一些实用程序以利用特定于每种颜色模式的样式。

例如，尽管在<div>上使用了data-bs-theme="dark"，但<div>没有background-color属性因为它在<body>上设置. 因此，如果您想让color和background-color适应，则需要添加.text-body和 .bg-body。

This should be shown in a dark theme at all times.

This should be shown in a light theme at all times.

HTML

<div data-bs-theme="dark" class="p-3 text-body bg-body">
  <nav aria-label="breadcrumb">
    <ol class="breadcrumb">
      <li class="breadcrumb-item"><a href="#">Color modes</a></li>
      <li class="breadcrumb-item active" aria-current="page">Dark</li>
    </ol>
  </nav>

  <p>This should be shown in a <strong>dark</strong> theme at all times.</p>

  <div class="progress mb-4">
    <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div>
  </div>

  <div class="dropdown mb-4">
    <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButtonDark2" data-bs-toggle="dropdown" aria-expanded="false">
      Dark dropdown
    </button>
    <ul class="dropdown-menu" aria-labelledby="dropdownMenuButtonDark2">
      <li><a class="dropdown-item active" href="#">Action</a></li>
      <li><a class="dropdown-item" href="#">Action</a></li>
      <li><a class="dropdown-item" href="#">Another action</a></li>
      <li><a class="dropdown-item" href="#">Something else here</a></li>
      <li><hr class="dropdown-divider"></li>
      <li><a class="dropdown-item" href="#">Separated link</a></li>
    </ul>
  </div>

  <div data-bs-theme="light" class="p-3 text-body bg-body rounded">
    <nav aria-label="breadcrumb">
      <ol class="breadcrumb">
        <li class="breadcrumb-item"><a href="#">Color modes</a></li>
        <li class="breadcrumb-item"><a href="#">Dark</a></li>
        <li class="breadcrumb-item active" aria-current="page">Light</li>
      </ol>
    </nav>

    <p>This should be shown in a <strong>light</strong> theme at all times.</p>

    <div class="progress mb-4">
      <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div>
    </div>

    <div class="dropdown">
      <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButtonLight2" data-bs-toggle="dropdown" aria-expanded="false">
        Light dropdown
      </button>
      <ul class="dropdown-menu" aria-labelledby="dropdownMenuButtonLight2">
        <li><a class="dropdown-item active" href="#">Action</a></li>
        <li><a class="dropdown-item" href="#">Action</a></li>
        <li><a class="dropdown-item" href="#">Another action</a></li>
        <li><a class="dropdown-item" href="#">Something else here</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#">Separated link</a></li>
      </ul>
    </div>
  </div>
</div>

用法

启用深色模式

通过将data-bs-theme="dark"属性添加到<html>元素，在整个项目中启用内置的深色模式。data-bs-theme这会将深色模式应用于所有组件和元素，但应用了特定属性的组件和元素除外。基于快速入门模板构建：

<!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/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-GLhlTQ8iRABdZLl6O3oVMWSktQOp6b7In1Zl3/Jr59b6EGGoI1aFkw7cmDA6j6gD" crossorigin="anonymous">
  </head>
  <body>
    <h1>Hello, world!</h1>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-w76AqPfDkMBDXo30jS1Sgez6pr3x5MlQ1ZAGC+nuZB+EYdgRZgiwxhTBTkF7CXvN" crossorigin="anonymous"></script>
  </body>
</html>

Bootstrap 尚未附带内置的颜色模式选择器，但如果您愿意，可以使用我们自己的文档中的那个。在 JavaScript 部分了解更多信息。

使用 Sass 构建

我们新的深色模式选项可供 Bootstrap 的所有用户使用，但它是通过数据属性而不是媒体查询来控制的，并且不会自动切换项目的颜色模式。你可以通过 Sass 更改$enable-dark-mode为false.

我们使用自定义 Sass mixincolor-mode()来帮助您控制颜色模式的应用方式。默认情况下，我们使用data属性方法，允许您创建更加用户友好的体验，您的访问者可以选择自动暗模式或控制他们的偏好（就像我们自己的文档中一样）。这也是一种简单且可扩展的方式，可以添加不同的主题和更多除了明暗之外的自定义颜色模式。

如果你想使用媒体查询并且只使颜色模式自动，你可以通过 Sass 变量更改 mixin 的默认类型。考虑以下代码片段及其编译后的 CSS 输出。

$color-mode-type: data;

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

输出到：

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

当设置为media-query：

$color-mode-type: media-query;

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

输出到：

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

自定义颜色模式

虽然颜色模式的主要用例是明暗模式，但自定义颜色模式也是可以的。使用自定义值作为颜色模式的名称创建您自己的data-bs-theme选择器，然后根据需要修改我们的 Sass 和 CSS 变量。我们选择创建一个单独的_variables-dark.scss样式表来容纳 Bootstrap 的暗模式特定 Sass 变量，但这不是您所必需的。

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

[data-bs-theme="blue"] {
  --bs-body-color: var(--bs-white);
  --bs-body-color-rgb: #{to-rgb($white)};
  --bs-body-bg: var(--bs-blue);
  --bs-body-bg-rgb: #{to-rgb($blue)};
  --bs-tertiary-bg: #{$blue-600};

  .dropdown-menu {
    --bs-dropdown-bg: #{mix($blue-500, $blue-600)};
    --bs-dropdown-link-active-bg: #{$blue-700};
  }

  .btn-secondary {
    --bs-btn-bg: #{mix($gray-600, $blue-400, .5)};
    --bs-btn-border-color: #{rgba($white, .25)};
    --bs-btn-hover-bg: #{darken(mix($gray-600, $blue-400, .5), 5%)};
    --bs-btn-hover-border-color: #{rgba($white, .25)};
    --bs-btn-active-bg: #{darken(mix($gray-600, $blue-400, .5), 10%)};
    --bs-btn-active-border-color: #{rgba($white, .5)};
    --bs-btn-focus-border-color: #{rgba($white, .5)};
    --bs-btn-focus-box-shadow: 0 0 0 .25rem rgba(255, 255, 255, .2);
  }
}

Example blue theme

Some paragraph text to show how the blue theme might look with written copy.

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

JavaScript

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

下面是支持它的 JavaScript。请随意检查我们自己的文档导航栏，看看它是如何使用我们自己的组件中的 HTML 和 CSS 实现的。请注意，如果您决定对您的颜色模式使用媒体查询，并且您更喜欢隐式控制，则可能需要修改或删除您的 JavaScript。

/*!
 * Color mode toggler for Bootstrap's docs (https://getbootstrap.com/)
 * Copyright 2011-2022 The Bootstrap Authors
 * Licensed under the Creative Commons Attribution 3.0 Unported License.
 */

(() => {
  'use strict'

  const storedTheme = localStorage.getItem('theme')

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

    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
  }

  const setTheme = function (theme) {
    if (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
      document.documentElement.setAttribute('data-bs-theme', 'dark')
    } else {
      document.documentElement.setAttribute('data-bs-theme', theme)
    }
  }

  setTheme(getPreferredTheme())

  const showActiveTheme = theme => {
    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')
    })

    btnToActive.classList.add('active')
    activeThemeIcon.setAttribute('href', svgOfActiveBtn)
  }

  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
    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')
          localStorage.setItem('theme', theme)
          setTheme(theme)
          showActiveTheme(theme)
        })
      })
  })
})()

CSS

变量

数十个根级 CSS 变量被重复作为暗模式的覆盖。这些被限定为颜色模式选择器，它默认为data-bs-theme但可以配置为使用prefers-color-scheme媒体查询。使用这些变量作为生成您自己的新颜色模式的指南。

    --#{$prefix}body-color: #{$body-color-dark};
    --#{$prefix}body-color-rgb: #{to-rgb($body-color-dark)};
    --#{$prefix}body-bg: #{$body-bg-dark};
    --#{$prefix}body-bg-rgb: #{to-rgb($body-bg-dark)};

    --#{$prefix}emphasis-color: #{$body-emphasis-color-dark};
    --#{$prefix}emphasis-color-rgb: #{to-rgb($body-emphasis-color-dark)};

    --#{$prefix}secondary-color: #{$body-secondary-color-dark};
    --#{$prefix}secondary-color-rgb: #{to-rgb($body-secondary-color-dark)};
    --#{$prefix}secondary-bg: #{$body-secondary-bg-dark};
    --#{$prefix}secondary-bg-rgb: #{to-rgb($body-secondary-bg-dark)};

    --#{$prefix}tertiary-color: #{$body-tertiary-color-dark};
    --#{$prefix}tertiary-color-rgb: #{to-rgb($body-tertiary-color-dark)};
    --#{$prefix}tertiary-bg: #{$body-tertiary-bg-dark};
    --#{$prefix}tertiary-bg-rgb: #{to-rgb($body-tertiary-bg-dark)};

    --#{$prefix}emphasis-color: #{$emphasis-color-dark};

    --#{$prefix}primary-text: #{$primary-text-dark};
    --#{$prefix}secondary-text: #{$secondary-text-dark};
    --#{$prefix}success-text: #{$success-text-dark};
    --#{$prefix}info-text: #{$info-text-dark};
    --#{$prefix}warning-text: #{$warning-text-dark};
    --#{$prefix}danger-text: #{$danger-text-dark};
    --#{$prefix}light-text: #{$light-text-dark};
    --#{$prefix}dark-text: #{$dark-text-dark};

    --#{$prefix}primary-bg-subtle: #{$primary-bg-subtle-dark};
    --#{$prefix}secondary-bg-subtle: #{$secondary-bg-subtle-dark};
    --#{$prefix}success-bg-subtle: #{$success-bg-subtle-dark};
    --#{$prefix}info-bg-subtle: #{$info-bg-subtle-dark};
    --#{$prefix}warning-bg-subtle: #{$warning-bg-subtle-dark};
    --#{$prefix}danger-bg-subtle: #{$danger-bg-subtle-dark};
    --#{$prefix}light-bg-subtle: #{$light-bg-subtle-dark};
    --#{$prefix}dark-bg-subtle: #{$dark-bg-subtle-dark};

    --#{$prefix}primary-border-subtle: #{$primary-border-subtle-dark};
    --#{$prefix}secondary-border-subtle: #{$secondary-border-subtle-dark};
    --#{$prefix}success-border-subtle: #{$success-border-subtle-dark};
    --#{$prefix}info-border-subtle: #{$info-border-subtle-dark};
    --#{$prefix}warning-border-subtle: #{$warning-border-subtle-dark};
    --#{$prefix}danger-border-subtle: #{$danger-border-subtle-dark};
    --#{$prefix}light-border-subtle: #{$light-border-subtle-dark};
    --#{$prefix}dark-border-subtle: #{$dark-border-subtle-dark};

    --#{$prefix}heading-color: #{$headings-color-dark};

    --#{$prefix}link-color: #{$link-color-dark};
    --#{$prefix}link-hover-color: #{$link-hover-color-dark};
    --#{$prefix}link-color-rgb: #{to-rgb($link-color-dark)};
    --#{$prefix}link-hover-color-rgb: #{to-rgb($link-hover-color-dark)};

    --#{$prefix}code-color: #{$code-color-dark};

    --#{$prefix}border-color: #{$border-color-dark};
    --#{$prefix}border-color-translucent: #{$border-color-translucent-dark};

Sass 变量

深色模式的 CSS 变量部分是从_variables-dark.scss. 这还包括一些自定义覆盖，用于更改整个组件中使用的嵌入式 SVG 的颜色。

$primary-text-dark:                 $blue-300;
$secondary-text-dark:               $gray-300;
$success-text-dark:                 $green-300;
$info-text-dark:                    $cyan-300;
$warning-text-dark:                 $yellow-300;
$danger-text-dark:                  $red-300;
$light-text-dark:                   $gray-100;
$dark-text-dark:                    $gray-300;

$primary-bg-subtle-dark:            $blue-900;
$secondary-bg-subtle-dark:          $gray-900;
$success-bg-subtle-dark:            $green-900;
$info-bg-subtle-dark:               $cyan-900;
$warning-bg-subtle-dark:            $yellow-900;
$danger-bg-subtle-dark:             $red-900;
$light-bg-subtle-dark:              $gray-800;
$dark-bg-subtle-dark:               mix($gray-800, $black);

$primary-border-subtle-dark:        $blue-700;
$secondary-border-subtle-dark:      $gray-700;
$success-border-subtle-dark:        $green-700;
$info-border-subtle-dark:           $cyan-800;
$warning-border-subtle-dark:        $yellow-800;
$danger-border-subtle-dark:         $red-700;
$light-border-subtle-dark:          $gray-700;
$dark-border-subtle-dark:           $gray-800;

$body-color-dark:                   $gray-500;
$body-bg-dark:                      $gray-900;
$body-emphasis-color-dark:          $gray-100;
$body-secondary-color-dark:         rgba($body-color-dark, .75);
$body-secondary-bg-dark:            $gray-800;
$body-tertiary-color-dark:          rgba($body-color-dark, .5);
$body-tertiary-bg-dark:             mix($gray-800, $gray-900, 50%);
$emphasis-color-dark:               $white;
$border-color-dark:                 $gray-700;
$border-color-translucent-dark:     rgba($white, .15);
$headings-color-dark:               #fff;
$link-color-dark:                   $blue-300;
$link-hover-color-dark:             $blue-200;
$code-color-dark:                   $pink-300;


//
// Forms
//

$form-select-indicator-color-dark:  $body-color-dark;
$form-select-indicator-dark:        url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='#{$form-select-indicator-color-dark}' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/></svg>");

$form-switch-color-dark:            rgba($white, .25);
$form-switch-bg-image-dark:         url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'><circle r='3' fill='#{$form-switch-color-dark}'/></svg>");


//
// Accordion
//

$accordion-button-icon-dark:         url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$primary-text-dark}'><path fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/></svg>");
$accordion-button-active-icon-dark:  url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$primary-text-dark}'><path fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/></svg>");

Sass 混入

深色模式的样式，以及您创建的任何自定义颜色模式，都可以通过可自定义的mixin适当地限定在data-bs-theme属性选择器或媒体查询范围内。color-mode()有关详细信息，请参阅Sass 用法部分。

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