核心方案是用 :root 定义语义化主题变量（如 --bg-primary），JS 通过 setProperty 动态修改并持久化，配合 data-theme 和 prefers-color-scheme 实现多主题无缝切换与系统适配。
核心思路是：用 :root 定义全局变量，用 var() 在样式中引用，再通过 JS 修改 :root 上的变量值来实时切换主题。整个过程无需重载页面、不依赖框架，纯原生可维护。
一、结构化定义主题变量
在 CSS 中统一管理所有可变样式值，避免散落各处：
- 所有主题变量必须以
--开头，推荐在:root中集中声明（等价于html元素，作用域最广） - 变量名保持语义化，如
--bg-primary、--text-secondary，不用--dark-bg这类带状态标签的命名，便于后续扩展多主题 - 为每个
var()调用提供回退值，例如color: var(--text-primary, #222)，防止变量未定义时样式崩溃 - 单位要提前绑定或配合
calc()使用，font-size: var(--size)px是无效写法；正确方式是--size: 16px或font-size: calc(var(--size-number) * 1px)
二、JS 控制主题切换逻辑
切换动作必须由 JavaScript 触发，CSS 本身无法响应点击事件：
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 使用
document.documentElement.style.setProperty()修改全局变量，这是标准且稳妥的方式（不要用document.querySelector('html')） - 批量修改时避免逐个调用
setProperty，可改用cssText或封装函数一次性设置多个值，减少重排开销 - 切换后立即读取当前主题状态，结合
localStorage持久化保存，例如存theme: 'sepia'，刷新页面时自动还原 - 监听系统级暗色模式变化（
prefers-color-scheme），作为默认 fallback，提升用户体验
三、支持多主题与渐进增强
不止亮/暗两种模式，还可拓展高对比度、护眼黄、深褐等风格：
立即学习“前端免费学习笔记（深入）”；
- 用
data-theme属性替代 class 切换，例如<html data-theme="dark">，对应 CSS 中写:root[data-theme="dark"] { --bg: #121212; }，更语义、更易调试 - 在
@media (prefers-color-scheme: dark)内重新定义变量，实现系统偏好自动适配，同时允许用户手动覆盖 - 对关键动画属性（如
transition）也使用变量控制，例如--transition-speed: 0.25s，让主题引擎真正贯穿 UI 全链路 - 禁用
@keyframes和content属性中直接使用var()（浏览器不支持），需用 JS 注入或预设 CSS 类替代
四、调试与容错要点
变量不生效？多数问题出在定义或引用环节：
- 检查拼写大小写是否完全一致：
--PrimaryColor≠--primaryColor，CSS 变量区分大小写 - 打开浏览器开发者工具 → “计算样式”面板，搜索变量名，确认是否被正确定义、继承和应用
- 确保变量已在使用前定义——CSS 是自上而下解析的，把
:root块放在样式表顶部 - IE 不支持 CSS 自定义属性，若需兼容，应在 JS 中检测
CSS.supports('color', 'var(--c)')并降级为传统 class 方案
