跳到主要内容
输入关键词开始搜索,↑ ↓ 选择,Enter 打开
没有找到匹配的文档

组件定制

了解我们如何以及为什么几乎所有组件都是响应式构建,并使用基础类和修饰符类。

基础类

Bootstrap 组件通常使用可组合的类构建:共享的基础类、变体类以及可选的主题类。例如,按钮可以从 .btn 开始,并将变体类如 .btn-solid 或 .btn-outline 与主题类如 .theme-primary 或 .theme-success 结合。

许多这些类是通过 Sass @each 对组件映射(例如用于变体和尺寸)以及主题映射的循环生成的。这保持了各组件类 API 的一致性,并允许一次更改映射即可更新所有相关选择器,包括适用的响应式变体。

查看我们的 Sass map和循环文档,了解如何自定义这些循环,并将 Bootstrap 的基础修饰符方法扩展到你自己的代码中。

主题变体

可主题化组件支持 主题变体——一组可组合的 .theme-* 类,它们可以为组件重新着色,而无需每个组件都使用硬编码的颜色类。这取代了以前将颜色嵌入每个组件(.btn-primary、.alert-success、.bg-warning 等)的模式,提供了一个一致的 API。

可主题化组件读取一组共享的通用 --bs-theme-* 令牌,用于其背景、前景、边框和聚焦样式——每个令牌都有一个回退到组件自身默认令牌的选项。当没有主题类存在时,将应用回退。向组件(或其祖先)添加 .theme-* 类,它将采用该主题的颜色。向嵌套子树添加 .theme-reset,以返回这些组件默认值。

令牌描述
--bs-theme-base主题所源自的原始基础颜色
--bs-theme-bg纯背景色,例如,纯色按钮或徽章
--bs-theme-bg-subtle低强调表面的细微背景色
--bs-theme-bg-muted柔和的背景,在微妙与实色之间
--bs-theme-fg默认表面上的前景/文本颜色
--bs-theme-fg-emphasis高对比度前景色
--bs-theme-border边框颜色
--bs-theme-contrast用于放置在实色上的文本/图标的对比色 --bs-theme-bg
--bs-theme-focus-ring对焦环颜色

.theme-{name} 类反映了我们的语义化 主题颜色——.theme-primary、.theme-secondary、.theme-success、.theme-danger 等等。它们是由 $theme-colors Sass map生成的,因此添加或重命名主题颜色会自动生成匹配的 .theme-* 类。每个条目通过 light-dark() 为浅色和深色模式定义了上述令牌:

SCSS
          // …
// One entry from $theme-colors in scss/_theme.scss
"primary": (
  "base": var(--blue-500),
  "fg": light-dark(var(--blue-600), var(--blue-400)),
  "fg-emphasis": light-dark(var(--blue-800), var(--blue-200)),
  "bg": var(--blue-500),
  "bg-subtle": light-dark(var(--blue-100), var(--blue-900)),
  "bg-muted": light-dark(var(--blue-200), var(--blue-800)),
  "border": light-dark(var(--blue-300), var(--blue-600)),
  "focus-ring": light-dark(color-mix(in oklch, var(--blue-500) 50%, var(--bg-body)), color-mix(in oklch, var(--blue-500) 75%, var(--bg-body))),
  "contrast": var(--white)
),
// …
        

要查看组件如何使用这些令牌,这里是在scss/_badge.scss中的徽章。它的color和background-color各自首先读取主题令牌,如果没有则回退到徽章自身的默认值(在 Sass 源码中,CSS 变量的写法不带--bs-前缀;PostCSS 在构建时会添加):

SCSS
          .badge {
  // …
  color: var(--theme-contrast, var(--badge-color));
  background-color: var(--theme-bg, var(--badge-bg));
}
        

没有主题类时,徽章使用其自己的默认值(--badge-bg,--badge-color)。添加 .theme-success 后,同一个元素将 --theme-bg 和 --theme-contrast 解析为成功角色代币——无需徽章特定的 .badge-success 选择器:

默认徽章 成功徽章
HTML
<span class="badge">Default badge</span>
<span class="badge theme-success">Success badge</span>

对于具有变体的组件,将变体类与主题类结合以为其上色。对于按钮,这意味着将.btn-solid或.btn-outline之类的变体与主题配对:

HTML
<button type="button" class="btn-solid theme-primary">Primary</button>
<button type="button" class="btn-outline theme-success">Success</button>
<button type="button" class="btn-subtle theme-danger">Danger</button>

因为主题标记是普通的 CSS 变量,你也可以将主题限定在一个容器中,让内部的所有内容继承它,或者为一次性的样式覆盖单个标记——无需编译 Sass:

CSS
          .my-brand {
  --bs-theme-bg: #6f42c1;
  --bs-theme-contrast: #fff;
}
        

要使你自己的组件可主题化,请遵循相同的模式:读取每个颜色属性的var(--theme-{role}, var(--my-component-{role})),它将响应设置在其自身或祖先上的任何.theme-*类。完整的角色令牌列表和推荐配对,请参见主题页面。

响应式

这些 Sass 循环也不仅限于颜色映射。你还可以生成组件的响应式变体。例如我们的响应式导航栏展开类,我们在其中将 @each 循环与 $breakpoints Sass map以及媒体查询包含混合使用。

// Generate series of responsive `.navbar-expand` classes for configuring
// where your navbar collapses and expands. Uses container queries so the
// navbar responds to its own width, not the viewport width.

// Mixin for expanded state styles (applied to descendants)
@mixin navbar-expanded {
  // Style the inner container since we can't style .navbar itself with container queries
  > .container,
  > .container-fluid,
  %navbar-expand-container {
    flex-wrap: nowrap;
    justify-content: flex-start;
  }

  .navbar-nav {
    --nav-link-padding-x: var(--navbar-nav-link-padding-x);
    flex-direction: row;
  }

  .navbar-toggler {
    display: none !important; // stylelint-disable-line declaration-no-important
  }

  [class*="drawer"] {
    // stylelint-disable declaration-no-important
    // Reset native <dialog> UA styles and below-breakpoint drawer styles.
    // Must use !important to override both UA <dialog> defaults and the
    // responsive drawer styles from media-breakpoint-down().
    position: static !important;
    inset: auto !important;
    z-index: auto;
    display: flex !important;
    flex-grow: 1;
    width: auto !important;
    max-width: none !important;
    height: auto !important;
    max-height: none !important;
    padding: 0;
    margin: 0;
    overflow: visible !important;
    visibility: visible !important;
    background-color: transparent !important;
    border: 0 !important;
    transform: none !important;
    @include box-shadow(none);
    @include transition(none);
    // stylelint-enable declaration-no-important

    .drawer-header {
      display: none !important; // stylelint-disable-line declaration-no-important
    }

    .drawer-body {
      display: flex;
      flex-grow: 1;
      flex-direction: row;
      align-items: center;
      padding: 0;
      overflow-y: visible;
    }
  }
}

// Always expanded (no responsive behavior)
.navbar-expand {
  @include navbar-expanded();

  // Also set on navbar itself for non-responsive case
  flex-wrap: nowrap;
  justify-content: flex-start;
}

// Responsive navbar expand classes using container queries
@include loop-breakpoints-down($navbar-breakpoints) using ($breakpoint, $next, $prefix) {
  @if $next {
    .#{$prefix}navbar-expand {
      @include container-breakpoint-up($next) {
        @include navbar-expanded();
      }
    }
  }
}

如果你修改你的 $breakpoints,你的更改将应用于所有迭代该映射的循环。

$breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 1024px,
  xl: 1280px,
  2xl: 1536px
);

有关如何修改我们的 Sass map和变量的更多信息和示例,请参阅网格文档的 CSS 部分。

创建你自己的

我们鼓励你在使用 Bootstrap 构建时采用这些指南,以创建你自己的组件。我们自己也将这种方法扩展到文档和示例中的自定义组件中。像我们的提示框这样的组件的构建方式与我们提供的组件相同,都使用基础类和修饰类。

这是一个提示框。 我们为文档自定义了它,以便我们的信息能够突出显示给你。它通过修饰类有三种变体。
HTML
          <div class="callout">...</div>
        

在你的 CSS 中,你可能会有如下内容,其中大部分样式是通过 .callout 完成的。然后,每个变体之间的独特样式是通过修饰类来控制的。

SCSS
          // Base class
.callout {}

// Modifier classes
.callout-info {}
.callout-warning {}
.callout-danger {}
        

对于呼叫框,那种独特的样式只是一个 border-left-color。当你将该基础类与其中一个修饰类组合时,你就得到完整的组件家族:

这是一个信息提示。 示例文本以显示其效果。

这是一个警告提示。 示例文本用于展示它的作用。

这是一个危险提示。 示例文本以显示其效果。