Skip to main content Skip to docs navigation

CSS 变量

使用 Bootstrap 的 CSS 自定义属性，实现快速且具有前瞻性的设计和开发。

目录

Bootstrap 在其编译后的 CSS 中包含许多 CSS 自定义属性（变量），可以进行实时自定义，而无需重新编译 Sass。在使用浏览器检查器、代码沙盒或进行一般原型设计时，这些属性可以轻松访问常用值，例如我们的主题颜色、断点和主要字体堆栈。

🌐 Bootstrap includes many CSS custom properties (variables) in its compiled CSS for real-time customization without the need to recompile Sass. These provide easy access to commonly used values like our theme colors, breakpoints, and primary font stacks when working in your browser’s inspector, a code sandbox, or general prototyping.

我们所有的自定义属性都以 bs- 为前缀，以避免与第三方 CSS 冲突。

根变量

🌐 Root variables

这里是我们包含的变量（注意 :root 是必须的），它们可以在加载 Bootstrap 的 CSS 的任何地方访问。它们位于我们的 _root.scss 文件中，并包含在我们编译的 dist 文件中。

🌐 Here are the variables we include (note that the :root is required) that can be accessed anywhere Bootstrap’s CSS is loaded. They’re located in our _root.scss file and included in our compiled dist files.

默认

🌐 Default

这些 CSS 变量随处可用，无论颜色模式如何。

🌐 These CSS variables are available everywhere, regardless of color mode.

:root,
[data-bs-theme=light] {
  --bs-blue: #0d6efd;
  --bs-indigo: #6610f2;
  --bs-purple: #6f42c1;
  --bs-pink: #d63384;
  --bs-red: #dc3545;
  --bs-orange: #fd7e14;
  --bs-yellow: #ffc107;
  --bs-green: #198754;
  --bs-teal: #20c997;
  --bs-cyan: #0dcaf0;
  --bs-black: #000;
  --bs-white: #fff;
  --bs-gray: #6c757d;
  --bs-gray-dark: #343a40;
  --bs-gray-100: #f8f9fa;
  --bs-gray-200: #e9ecef;
  --bs-gray-300: #dee2e6;
  --bs-gray-400: #ced4da;
  --bs-gray-500: #adb5bd;
  --bs-gray-600: #6c757d;
  --bs-gray-700: #495057;
  --bs-gray-800: #343a40;
  --bs-gray-900: #212529;
  --bs-primary: #0d6efd;
  --bs-secondary: #6c757d;
  --bs-success: #198754;
  --bs-info: #0dcaf0;
  --bs-warning: #ffc107;
  --bs-danger: #dc3545;
  --bs-light: #f8f9fa;
  --bs-dark: #212529;
  --bs-primary-rgb: 13, 110, 253;
  --bs-secondary-rgb: 108, 117, 125;
  --bs-success-rgb: 25, 135, 84;
  --bs-info-rgb: 13, 202, 240;
  --bs-warning-rgb: 255, 193, 7;
  --bs-danger-rgb: 220, 53, 69;
  --bs-light-rgb: 248, 249, 250;
  --bs-dark-rgb: 33, 37, 41;
  --bs-primary-text-emphasis: #052c65;
  --bs-secondary-text-emphasis: #2b2f32;
  --bs-success-text-emphasis: #0a3622;
  --bs-info-text-emphasis: #055160;
  --bs-warning-text-emphasis: #664d03;
  --bs-danger-text-emphasis: #58151c;
  --bs-light-text-emphasis: #495057;
  --bs-dark-text-emphasis: #495057;
  --bs-primary-bg-subtle: #cfe2ff;
  --bs-secondary-bg-subtle: #e2e3e5;
  --bs-success-bg-subtle: #d1e7dd;
  --bs-info-bg-subtle: #cff4fc;
  --bs-warning-bg-subtle: #fff3cd;
  --bs-danger-bg-subtle: #f8d7da;
  --bs-light-bg-subtle: #fcfcfd;
  --bs-dark-bg-subtle: #ced4da;
  --bs-primary-border-subtle: #9ec5fe;
  --bs-secondary-border-subtle: #c4c8cb;
  --bs-success-border-subtle: #a3cfbb;
  --bs-info-border-subtle: #9eeaf9;
  --bs-warning-border-subtle: #ffe69c;
  --bs-danger-border-subtle: #f1aeb5;
  --bs-light-border-subtle: #e9ecef;
  --bs-dark-border-subtle: #adb5bd;
  --bs-white-rgb: 255, 255, 255;
  --bs-black-rgb: 0, 0, 0;
  --bs-font-sans-serif: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
  --bs-gradient: linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0));
  --bs-body-font-family: var(--bs-font-sans-serif);
  --bs-body-font-size: 1rem;
  --bs-body-font-weight: 400;
  --bs-body-line-height: 1.5;
  --bs-body-color: #212529;
  --bs-body-color-rgb: 33, 37, 41;
  --bs-body-bg: #fff;
  --bs-body-bg-rgb: 255, 255, 255;
  --bs-emphasis-color: #000;
  --bs-emphasis-color-rgb: 0, 0, 0;
  --bs-secondary-color: rgba(33, 37, 41, 0.75);
  --bs-secondary-color-rgb: 33, 37, 41;
  --bs-secondary-bg: #e9ecef;
  --bs-secondary-bg-rgb: 233, 236, 239;
  --bs-tertiary-color: rgba(33, 37, 41, 0.5);
  --bs-tertiary-color-rgb: 33, 37, 41;
  --bs-tertiary-bg: #f8f9fa;
  --bs-tertiary-bg-rgb: 248, 249, 250;
  --bs-heading-color: inherit;
  --bs-link-color: #0d6efd;
  --bs-link-color-rgb: 13, 110, 253;
  --bs-link-decoration: underline;
  --bs-link-hover-color: #0a58ca;
  --bs-link-hover-color-rgb: 10, 88, 202;
  --bs-code-color: #d63384;
  --bs-highlight-color: #212529;
  --bs-highlight-bg: #fff3cd;
  --bs-border-width: 1px;
  --bs-border-style: solid;
  --bs-border-color: #dee2e6;
  --bs-border-color-translucent: rgba(0, 0, 0, 0.175);
  --bs-border-radius: 0.375rem;
  --bs-border-radius-sm: 0.25rem;
  --bs-border-radius-lg: 0.5rem;
  --bs-border-radius-xl: 1rem;
  --bs-border-radius-xxl: 2rem;
  --bs-border-radius-2xl: var(--bs-border-radius-xxl);
  --bs-border-radius-pill: 50rem;
  --bs-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
  --bs-box-shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
  --bs-box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);
  --bs-box-shadow-inset: inset 0 1px 2px rgba(0, 0, 0, 0.075);
  --bs-focus-ring-width: 0.25rem;
  --bs-focus-ring-opacity: 0.25;
  --bs-focus-ring-color: rgba(13, 110, 253, 0.25);
  --bs-form-valid-color: #198754;
  --bs-form-valid-border-color: #198754;
  --bs-form-invalid-color: #dc3545;
  --bs-form-invalid-border-color: #dc3545;
}

夜间模式

🌐 Dark mode

这些变量的范围仅限于我们内置的夜间模式。

🌐 These variables are scoped to our built-in dark mode.

[data-bs-theme=dark] {
  color-scheme: dark;
  --bs-body-color: #dee2e6;
  --bs-body-color-rgb: 222, 226, 230;
  --bs-body-bg: #212529;
  --bs-body-bg-rgb: 33, 37, 41;
  --bs-emphasis-color: #fff;
  --bs-emphasis-color-rgb: 255, 255, 255;
  --bs-secondary-color: rgba(222, 226, 230, 0.75);
  --bs-secondary-color-rgb: 222, 226, 230;
  --bs-secondary-bg: #343a40;
  --bs-secondary-bg-rgb: 52, 58, 64;
  --bs-tertiary-color: rgba(222, 226, 230, 0.5);
  --bs-tertiary-color-rgb: 222, 226, 230;
  --bs-tertiary-bg: #2b3035;
  --bs-tertiary-bg-rgb: 43, 48, 53;
  --bs-primary-text-emphasis: #6ea8fe;
  --bs-secondary-text-emphasis: #a7acb1;
  --bs-success-text-emphasis: #75b798;
  --bs-info-text-emphasis: #6edff6;
  --bs-warning-text-emphasis: #ffda6a;
  --bs-danger-text-emphasis: #ea868f;
  --bs-light-text-emphasis: #f8f9fa;
  --bs-dark-text-emphasis: #dee2e6;
  --bs-primary-bg-subtle: #031633;
  --bs-secondary-bg-subtle: #161719;
  --bs-success-bg-subtle: #051b11;
  --bs-info-bg-subtle: #032830;
  --bs-warning-bg-subtle: #332701;
  --bs-danger-bg-subtle: #2c0b0e;
  --bs-light-bg-subtle: #343a40;
  --bs-dark-bg-subtle: #1a1d20;
  --bs-primary-border-subtle: #084298;
  --bs-secondary-border-subtle: #41464b;
  --bs-success-border-subtle: #0f5132;
  --bs-info-border-subtle: #087990;
  --bs-warning-border-subtle: #997404;
  --bs-danger-border-subtle: #842029;
  --bs-light-border-subtle: #495057;
  --bs-dark-border-subtle: #343a40;
  --bs-heading-color: inherit;
  --bs-link-color: #6ea8fe;
  --bs-link-hover-color: #8bb9fe;
  --bs-link-color-rgb: 110, 168, 254;
  --bs-link-hover-color-rgb: 139, 185, 254;
  --bs-code-color: #e685b5;
  --bs-highlight-color: #dee2e6;
  --bs-highlight-bg: #664d03;
  --bs-border-color: #495057;
  --bs-border-color-translucent: rgba(255, 255, 255, 0.15);
  --bs-form-valid-color: #75b798;
  --bs-form-valid-border-color: #75b798;
  --bs-form-invalid-color: #ea868f;
  --bs-form-invalid-border-color: #ea868f;
}

组件变量

🌐 Component variables

Bootstrap 5 正越来越多地将自定义属性用作各种组件的本地变量。这样我们可以减少编译后的 CSS，确保样式不会在嵌套表格等地方继承，并允许在 Sass 编译后对 Bootstrap 组件进行一些基本的重新样式化和扩展。

🌐 Bootstrap 5 is increasingly making use of custom properties as local variables for various components. This way we reduce our compiled CSS, ensure styles aren’t inherited in places like nested tables, and allow some basic restyling and extending of Bootstrap components after Sass compilation.

查看我们的表格文档，了解一些关于我们如何使用 CSS 变量的见解（[[docsref:/content/tables#how-do-the-variants-and-accented-tables-work]]）。从 v5.2.0 开始，我们的导航栏也使用 CSS 变量（[[docsref:/components/navbar#css]]）。我们还在整个网格中使用 CSS 变量——主要用于间距，以及新的可选 CSS 网格（[[docsref:/layout/css-grid]]）——未来会在更多组件中使用。

🌐 Have a look at our table documentation for some insight into how we’re using CSS variables. Our navbars also use CSS variables as of v5.2.0. We’re also using CSS variables across our grids—primarily for gutters the new opt-in CSS grid—with more component usage coming in the future.

在可能的情况下，我们会在基础组件级别分配 CSS 变量（例如，导航栏及其子组件使用 .navbar）。这可以减少对在哪里以及如何自定义的猜测，并允许我们的团队在未来的更新中轻松修改。

🌐 Whenever possible, we'll assign CSS variables at the base component level (e.g., .navbar for navbar and its sub-components). This reduces guessing on where and how to customize, and allows for easy modifications by our team in future updates.

前缀

🌐 Prefix

大多数 CSS 变量使用前缀以避免与你自己的代码库冲突。除了每个 CSS 变量都需要的 --，还会有这个前缀。

🌐 Most CSS variables use a prefix to avoid collisions with your own codebase. This prefix is in addition to the -- that’s required on every CSS variable.

通过 $prefix Sass 变量自定义前缀。默认情况下，它设置为 bs-（注意后面的短横）。

🌐 Customize the prefix via the $prefix Sass variable. By default, it’s set to bs- (note the trailing dash).

示例

🌐 Examples

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

🌐 CSS variables offer similar flexibility to Sass’s variables, but without the need for compilation before being served to the browser. For example, here we’re resetting our page’s font and link styles with CSS variables.

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

焦点变量

🌐 Focus variables

Added in v5.3.0

Bootstrap 使用 Sass 和 CSS 变量的组合提供自定义 :focus 样式，这些样式可以选择性地添加到特定组件和元素中。我们尚未全局覆盖所有 :focus 样式。

🌐 Bootstrap provides custom :focus styles using a combination of Sass and CSS variables that can be optionally added to specific components and elements. We do not yet globally override all :focus styles.

在我们的 Sass 中，我们设置了可以在编译前自定义的默认值。

🌐 In our Sass, we set default values that can be customized before compiling.

scss/_variables.scss 
$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;

这些变量随后被重新分配给 :root 级 CSS 变量，可以实时自定义，包括 x 和 y 偏移选项（默认值为其备用值 0）。

🌐 Those variables are then reassigned to :root level CSS variables that can be customized in real-time, including with options for x and y offsets (which default to their fallback value of 0).

scss/_root.scss 
--#{$prefix}focus-ring-width: #{$focus-ring-width};
--#{$prefix}focus-ring-opacity: #{$focus-ring-opacity};
--#{$prefix}focus-ring-color: #{$focus-ring-color};

网格断点

🌐 Grid breakpoints

虽然我们将网格断点作为 CSS 变量包含（xs 除外），但请注意，CSS 变量在媒体查询中不起作用。这是 CSS 变量规范中设计如此，但随着未来对 env() 变量的支持，这可能会有所变化。查看 这个 Stack Overflow 回答 获取一些有用的链接。与此同时，你可以在其他 CSS 场景中以及在 JavaScript 中使用这些变量。

🌐 While we include our grid breakpoints as CSS variables (except for xs), be aware that CSS variables do not work in media queries. This is by design in the CSS spec for variables, but may change in coming years with support for env() variables. Check out this Stack Overflow answer for some helpful links. In the meantime, you can use these variables in other CSS situations, as well as in your JavaScript.