模板引擎仅负责将主题状态（如isDarkMode）一次性渲染为HTML属性或类名，不执行运行时样式切换；完整切换需JS监听事件、读取存储并同步DOM类、CSS变量与localStorage，CSS变量应统一接管所有可变样式。
模板引擎如何参与样式切换逻辑
模板本身不执行样式切换，它只负责把主题数据（比如 theme 变量或 isDarkMode 标志）渲染进 HTML 结构中，为后续 JS 或 CSS 提供上下文。例如 Handlebars 模板里写 {{#if isDarkMode}}dark-theme{{/if}}，最终输出 <body class="dark-theme">；Vue 中用 :class="{ 'dark-theme': isDarkMode }" 也是同理——模板只是把状态“具象化”成 DOM 属性或类名。
常见错误现象：直接在模板里写内联样式如 style="color: {{ textColor }}"，看似动态，实则绕过 CSS 变量机制，无法响应主题更新、难维护、且丢失浏览器原生样式层控制能力。
- 使用场景：服务端渲染（如 Django/Jinja2）、静态站点生成（如 Hugo）、或客户端框架（React/Vue）的初始挂载阶段
- 关键点：模板只做“一次性的状态快照”，不替代
document.documentElement.classList.toggle()或document.body.setAttribute()这类运行时操作 - 性能影响：服务端模板渲染主题会增加首屏 TTFB，但避免了客户端 JS 注入样式前的 FOUC；客户端模板则依赖 JS 执行时机，需配合
data-theme预设或 SSR 同构处理
为什么不能只靠模板完成完整切换
模板只在页面生成时起作用，而用户中途点击切换主题、系统偏好变更（prefers-color-scheme）、或 localStorage 更新后，模板已不再运行。此时必须由 JavaScript 补位：监听事件、读取存储、修改 DOM 类或 CSS 变量值。
典型问题：用模板渲染了 class="light-theme"，但用户点按钮切暗色，JS 却只改了 :root 变量，而组件内部仍用 class 写死样式（如 .light-theme .btn { background: white }），结果新变量没生效，旧 class 又没删——样式错乱。
立即学习“前端免费学习笔记（深入）”；
- 必须统一控制入口：要么全走 CSS 变量 +
document.documentElement.style.setProperty()，要么全走 class 切换 +document.body.classList.replace() - 模板生成的初始 class（如
data-theme="dark"）应仅作 fallback 或 SSR 标记，不可与运行时逻辑混用 - Vue/React 等框架中，模板中的
v-bind:class或className必须绑定到响应式状态，否则 props 更新时不会重渲染
CSS 变量 + 模板组合的最小可行结构
最简健壮结构是：模板负责注入初始主题标识（用于 SSR 和 SEO），CSS 变量定义所有可变样式，JS 负责运行时同步三者——DOM 类、CSS 变量、localStorage。
示例结构：
<html data-theme="light">
<head>
<style>
:root {
--bg: #fff;
--text: #333;
}
[data-theme="dark"] {
--bg: #1a1a1a;
--text: #eee;
}
</style>
</head>
<body style="background-color: var(--bg); color: var(--text);">
<button onclick="toggleTheme()">切换</button>
</body>
<script>
function toggleTheme() {
const current = document.documentElement.getAttribute('data-theme');
const next = current === 'light' ? 'dark' : 'light';
document.documentElement.setAttribute('data-theme', next);
localStorage.setItem('theme', next);
}
// 页面加载时读取 localStorage 并应用
const saved = localStorage.getItem('theme');
if (saved) document.documentElement.setAttribute('data-theme', saved);
</script>
</html>
- 模板只需输出
data-theme初始值，不参与任何样式计算 - 所有颜色、间距、阴影等必须通过
var(--xxx)引用，禁止硬编码 - 注意：
[data-theme="dark"]是属性选择器，不是类名，避免和.dark类冲突
容易被忽略的兼容性断点
模板渲染出的 data-theme 值若含空格、斜杠、特殊字符（如 halloween-2026），CSS 属性选择器会失效，因为 [data-theme="halloween-2026"] 是合法的，但若模板误输出 data-theme="halloween / 2026"，CSS 就无法匹配。
更隐蔽的问题是：某些模板引擎（如早期 EJS）默认对变量做 HTML 转义，<div class="{{ theme }}"> 若 theme 是 dark&high-contrast，转义后变成 dark&high-contrast，JS 读取时拿到的是转义字符串，导致类名不匹配。
- 务必校验模板输出的
data-theme或class值是否与 JS 读取、CSS 选择器完全一致 - 服务端模板中，对主题变量使用
raw或safe过滤器（Jinja2 的{{ theme|safe }}） - 客户端模板（如 Vue）中，确保
v-bind:class绑定的是原始字符串，而非被 computed 处理成对象又漏掉 key
