用途
bootstrap-customize 用于回答和指导 Bootstrap 5.3 的定制化问题,例如如何自定义 Bootstrap、如何创建自定义主题、可以覆盖哪些 Sass 变量等。它围绕 Bootstrap 提供的 Sass 变量、CSS 自定义属性(文档中称为 CSS variables)与主题系统展开,并包含内置配色模式(color modes)。
主要能力
1. CSS 变量(运行时定制)
无需重新编译即可修改样式,可在任意层级覆盖,例如在 :root 全局覆盖 --bs-primary、--bs-body-font-family;在组件级覆盖 --bs-card-bg、--bs-card-border-color;在局部作用域覆盖 --bs-btn-bg 等按钮变量。还可通过 $prefix Sass 变量修改 bs- 前缀以避免与其他框架冲突,例如 $prefix: "myapp-" 会生成 --myapp-primary 等。
2. Sass 变量(编译时定制)
完整主题化需在导入 Bootstrap 之前覆盖 Sass 变量,顺序为先导入 functions,再覆盖变量,最后导入 bootstrap。示例中覆盖了 $primary、$secondary、$font-family-base、$border-radius、$enable-shadows 等。
3. 颜色系统
包含八种默认主题色(primary、secondary、success、info、warning、danger、light、dark),通过 $theme-colors 映射管理。可通过 map-merge 向 $theme-colors 添加自定义颜色,从而自动生成 .bg-、.text-、.btn-* 等工具类。若要让 alerts、badges、list-groups 在深色模式下正确显示,还需在 $theme-colors-text、$theme-colors-bg-subtle、$theme-colors-border-subtle 及其 dark 版本中定义对应变体。可用 map-remove 移除颜色,但 primary、success、danger 为必需键,不能移除,否则会导致 Sass 编译错误;secondary、info、warning、light、dark 可安全移除。
4. 配色模式(深色/浅色)
在 html 或任意元素上设置 data-bs-theme 属性即可启用,如 data-bs-theme="light"、data-bs-theme="dark",也可对单个组件设置。提供 JavaScript 切换示例,并支持通过 window.matchMedia('(prefers-color-scheme: dark)') 读取和监听系统偏好。实现方式由 $color-mode-type 控制:data 方式(默认)使用 data-bs-theme 属性,支持按组件控制、用户偏好覆盖系统设置、运行时切换;media-query 方式使用 prefers-color-scheme 自动适配,无需 JavaScript、无运行时开销,但不支持按组件控制且用户无法通过界面覆盖。还可定义 light/dark 之外的完全自定义配色模式(如 blue 主题,详见 references/sass-variables.md)。
5. Sass 函数
提供 tint-color(与白色混合提亮)、shade-color(与黑色混合加深)、shift-color(按权重正负自动提亮或加深)、color-contrast(获取可访问的对比色)等函数,以及 escape-svg()、add()/subtract() 等。完整函数与 mixin 参考见 references/sass-functions-mixins.md。
6. 关键 Sass 变量
涵盖排版($font-family-base、$font-size-base、$font-weight-、$line-height-base、$headings- 等)、间距($spacer 与 $spacers 映射)、圆角($border-radius 及 sm/lg/xl/xxl/pill)、选项开关($enable-caret、$enable-rounded、$enable-shadows、$enable-gradients、$enable-transitions、$enable-reduced-motion、$enable-smooth-scroll、$enable-grid-classes、$enable-container-classes、$enable-negative-margins、$enable-dark-mode、$color-mode-type)以及聚焦环变量($focus-ring-width、$focus-ring-opacity、$focus-ring-color、$focus-ring-blur、$focus-ring-box-shadow)。
7. 组件定制
提供按钮(全局变量与按变体的 CSS 变量)、卡片($card-spacer-y、$card-spacer-x、$card-border-、$card-bg、$card-cap-bg)、表单($input-padding-、$input-font-size、$input-border-radius、$input-border-color、$input-focus-border-color、$input-focus-box-shadow)等组件的变量示例。
8. 组件架构与自定义组件
Bootstrap 采用 base-modifier 模式:基础类提供核心样式,修饰类添加变体。Bootstrap 通过 @each 遍历 $theme-colors 生成颜色变体;向 $theme-colors 添加颜色会自动生成 alerts、buttons、badges、list-groups 等变体。可按同样模式创建自定义组件与变体(如 .callout 与 .callout-primary)。创建自定义组件时可复用 Bootstrap 的间距映射、颜色变量、边框、阴影与 media-breakpoint-up 响应式断点。
使用方式
以 Sass 定制为例,顺序为:先 @import "bootstrap/scss/functions",再覆盖默认变量,最后 @import "bootstrap/scss/bootstrap"。变量必须在 functions 之后、其他 Bootstrap 导入之前设置。运行时定制则直接覆盖 CSS 变量。
优化与生产实践
- 精简 Sass 导入:仅导入必需核心(functions、variables、variables-dark、maps、mixins、root)与所用组件(如 reboot、type、containers、grid、buttons);完整示例见 examples/selective-imports.scss。
- 精简 JavaScript 导入:按需导入单个插件,如 'bootstrap/js/dist/modal'、'bootstrap/js/dist/dropdown'、'bootstrap/js/dist/collapse',并手动初始化;部分插件有依赖(如 Dropdown 依赖 Popper.js)。
- 使用 PurgeCSS 移除未用 CSS,需将 show、fade、collapse、modal、offcanvas 等动态类加入 safelist。
- Autoprefixer:通过 .browserslistrc 配置浏览器支持(示例为 Bootstrap 默认配置)。
- 生产最佳实践:使用 bootstrap.min.css 与 bootstrap.bundle.min.js;启用 gzip 或 Brotli(如 nginx 的 gzip on);非关键脚本使用 defer;始终通过 HTTPS 提供资源。
安全注意事项
Bootstrap 在 CSS 中使用内联 SVG(data: URI)。在严格的内容安全策略(CSP)下,部分组件可能无法正确显示,受影响组件包括折叠面板、轮播控制、关闭按钮、表单控件(复选框、单选框、开关、校验图标)、导航栏切换按钮、下拉选择箭头。冲突症状包括复选框不显示对勾、折叠面板缺少图标、导航栏汉堡菜单异常、下拉选择缺少箭头。解决思路:使用 escape-svg() 配合本地托管 SVG(如 $form-check-input-checked-bg-image: url("/assets/icons/check.svg"));在安全要求允许时调整 CSP 允许内联 SVG data URI;或用 Bootstrap Icons 字体替换 SVG 图标。
其他资源
参考文件:references/sass-variables.md(完整 Sass 变量参考)、references/sass-functions-mixins.md(完整函数与 mixin 参考)。示例文件:examples/color-mode-toggle.html(带系统偏好检测的深/浅模式切换)、examples/custom-theme-demo.html(无需 Sass 编译的运行时 CSS 变量主题)。
限制
上述内容均基于 Bootstrap 5.3 及其官网说明;该技能的具体安装方式、收费与价格信息、支持的平台或框架版本范围、实际使用效果等,资料中暂未提供。