Bootstrap 5.3+原生支持暗黑模式但默认禁用，需手动激活data-bs-theme="dark"属性、补全CSS变量及持久化逻辑，并注意导航栏需用navbar-dark/bg-dark类而非主题属性。
Bootstrap 5.3 及以上版本原生支持暗黑模式，但该能力默认处于禁用状态，需手动激活并补全检测逻辑与持久化机制。以下是针对其实现原理、适用方式及实际表现的客观说明：
一、Bootstrap 5 暗黑模式的技术基础
Bootstrap 5.3 引入 data-bs-theme="dark" 属性作为主题开关，配合 CSS 自定义变量（如 --bs-body-bg、--bs-body-color）实现样式切换。该机制仅在 :root 或 html 元素 上设置才生效，且依赖已编译的变量值注入——若缺失对应变量定义，即使添加属性页面也不会变暗。
1、确认 Bootstrap 版本：检查 bootstrap.min.css 文件头部注释，必须为 v5.3.0 或更高版本。
2、在 html 标签中添加属性：data-bs-theme="dark"，例如：<html data-bs-theme="dark">。
3、确保引入的 CSS 包含完整的暗色变量定义，或额外加载 bootstrap-dark-5 等补全样式包。
二、组件级局部启用暗色模式
无需全局切换时，可将 data-bs-theme="dark" 属性直接添加至特定组件容器，使该组件及其子元素独立应用暗色样式，不影响其余页面区域。
1、定位目标组件，例如一个卡片容器：<div class="card">。
2、为其添加属性：data-bs-theme="dark"，即：<div class="card" data-bs-theme="dark">。
3、验证该卡片内文本、边框、背景等是否按暗色变量渲染，注意其父级若设为 light 主题则不会干扰此局部设定。
三、使用 bootstrap-dark-5 补全方案
bootstrap-dark-5 并非独立主题框架，而是对 Bootstrap 5.3+ 原生能力的增强补丁，提供预设变量、RTL 暗色修复及图标兼容性支持，解决原生实现中常见的变量缺失与渲染异常问题。
1、通过 npm 安装：npm install bootstrap-dark-5。
2、在 SCSS 入口文件中，先导入 Bootstrap 原始样式，再导入 bootstrap-dark-5 的变量与规则。
3、确保构建流程正确编译 SCSS，使 --bs-* 变量在 :root 中被覆盖并生效。
四、导航栏明暗主题的语义化控制
导航栏不依赖 data-bs-theme 属性进行局部控制，而应使用语义类组合：深色模式下必须同时应用 navbar-dark 与 bg-dark，前者控制文字/图标为高对比白色，后者控制背景色；浅色模式则对应 navbar-light 与 bg-light。
1、移除导航栏上可能存在的 data-bs-theme="dark" 属性，避免类名优先级冲突。
2、为导航栏添加动态绑定类，例如 Vue 中：:class="[isDark ? 'navbar-dark bg-dark' : 'navbar-light bg-light']"。
3、确保未混用 bg-body-tertiary 等固定浅灰类，否则会覆盖动态背景色。
五、暗色模式的实际表现优缺点
优点方面：在低光环境下显著降低眼睛疲劳；OLED 屏幕设备可减少像素点亮耗，延长续航；高对比度设计提升内容可读性与专注度；支持全局与组件级双层控制，适配多样化 UI 需求。
缺点方面：原生实现需开发者自行补全系统偏好监听与 localStorage 持久化逻辑；若未正确注入 CSS 变量，data-bs-theme="dark" 将完全无效；部分第三方插件或自定义组件可能未适配暗色变量，导致颜色断裂；RTL 布局下存在暗色渲染偏差，需 bootstrap-dark-5 等补丁修复。
