直接用<theme-switcher>不现实，必须用data-theme属性+CSS变量+document.documentElement操作，确保值大小写一致、localStorage同步、优先级明确。
直接用 <custom-element> 构建主题切换器不现实——HTML 没有原生的「自定义元素」能直接接管主题逻辑，真正可行的是用标准 DOM 元素 + data-theme 属性 + CSS 变量，再封装成可复用的 JS 逻辑。所谓「自定义元素」通常指开发者自己写的类或函数，不是浏览器内置标签。
为什么不能直接写 <theme-switcher> 标签
浏览器不识别未注册的自定义标签，<theme-switcher> 会被当作未知元素处理，样式和行为不会自动生效。即使调用 customElements.define() 注册，它也只负责渲染结构，主题切换的核心仍依赖 document.documentElement.setAttribute('data-theme', ...) 和 CSS 选择器匹配。
- 注册自定义元素本身不解决 CSS 变量作用域问题
- 所有主题样式最终都要靠
[data-theme="dark"]这类选择器触发，而非标签名 - 若强行用
<theme-switcher>，反而增加不必要的复杂度和兼容性风险（如 SSR 渲染、SEO 解析）
data-theme 值必须与 CSS 选择器严格一致
这是最常踩的坑：JS 设置了 data-theme="dark"，但 CSS 里写的是 [data-theme="Dark"] 或 [data-theme="DARK"]，切换就完全失效。
- 检查 CSS 中是否用了大小写敏感的值，比如
[data-theme="dark"]对应 JS 的setTheme('dark')，不能混用'Dark' - 避免空格或不可见字符：复制粘贴时可能带入全角空格或零宽字符，导致匹配失败
- 推荐统一用小写、连字符分隔，如
'light'/'dark'/'sepia'
切换逻辑必须作用在 document.documentElement
document.body.setAttribute('data-theme', 'dark') 是无效的——CSS 变量作用域在 :root，而 :root 等价于 document.documentElement（即 <html> 元素），不是 <body>。
立即学习“前端免费学习笔记（深入）”；
- 正确写法：
document.documentElement.setAttribute('data-theme', theme) - 如果页面已存在
data-theme，建议先移除再设置，避免残留旧值：document.documentElement.removeAttribute('data-theme'); - 部分框架（如 Vue）会劫持
document.documentElement，需确保操作时机在 DOM ready 之后
localStorage 保存后需立即同步到 DOM
仅存 localStorage 不会自动应用主题，页面加载时必须主动读取并设置 data-theme 属性，否则用户刷新页面就回到默认主题。
- 在脚本最开头执行：
const saved = localStorage.getItem('theme'); if (saved) document.documentElement.setAttribute('data-theme', saved); - 不要等
DOMContentLoaded再读取——FOUC（闪白）可能已经发生 - 如果同时支持系统偏好（
prefers-color-scheme），需在 localStorage 为空时 fallback，且优先级要明确：用户手动选择 > localStorage > 系统偏好
真正需要关注的不是「怎么造一个新标签」，而是确保 data-theme 的值、CSS 选择器、DOM 设置目标、持久化时机这四点严丝合缝。任何一环错位，主题就停在默认态不动。
