html暗黑模式与系统主题无关，需用window.matchmedia监听prefers-color-scheme并手动切换document.documentelement类名，配合css变量、localstorage缓存及第三方组件显式适配。
HTML暗黑模式不是系统主题的镜像
直接说结论：HTML暗黑模式和操作系统级暗黑主题是两套独立机制，浏览器不会自动把 prefers-color-scheme: dark 当作强制开关——它只是个提示信号，是否响应、何时响应、响应到什么程度，全由页面自己决定。
常见错误现象是开发者写了 @media (prefers-color-scheme: dark) 就以为万事大吉，结果用户切了系统暗色，页面部分区域（比如内联 SVG、Canvas 渲染内容、第三方组件样式）依然亮着，甚至文字反色导致不可读。
关键点在于：prefers-color-scheme 是只读媒体查询，它不触发重绘，也不接管 CSS 变量作用域。你得主动用它驱动 class 切换或变量注入。
怎么让 HTML 暗黑模式真正跟随系统变化
核心动作不是监听系统，而是监听媒体查询变更，并同步更新文档根节点状态。仅靠 CSS 媒体查询做不到动态响应 JS 逻辑或第三方库渲染。
- 用
window.matchMedia监听(prefers-color-scheme: dark)，并在回调中设置document.documentElement.classList.toggle('dark', matches) - 务必在初始化时也执行一次判断，避免首屏闪动或初始态错位
- 如果用了 CSS 自定义属性（如
--bg: #fff），需在:root和:root.dark中分别定义，不能只靠媒体查询嵌套覆盖 - 注意 SSR 场景：服务端无法获取客户端偏好，首次 HTML 必须留白或 fallback 到 light，JS 加载后再补全 dark 类
第三方组件和 Canvas 等非标准 DOM 元素怎么适配
这类内容不受 CSS 媒体查询影响，必须显式传参或监听事件。比如 Chart.js 默认不响应 prefers-color-scheme，ECharts 需手动调用 setOption 更新颜色配置。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
常见坑：
-
<canvas></canvas>绘图颜色硬编码为'#000'或'white'，没走 CSS 变量或 JS 主题状态 - 图标字体（如 Font Awesome）用 class 控制颜色，但未在
.dark下重置color，导致图标消失 - Web Components（如 Lit）中 Shadow DOM 内部样式未通过
:host-context(.dark)或属性绑定响应 - 图片资源（尤其是 SVG 内联）没提供
dark版本，也没用picture+media切换
为什么 localStorage 缓存主题比系统偏好更可靠
因为用户会主动“反系统”：有人系统设 dark，但某网站阅读体验差，就手动切回 light；也有人系统是 light，但夜间想护眼，单独开启该站暗色。这时候硬绑系统偏好反而违背用户意图。
实操建议：
- 首次访问按
matchMedia初始化，但立刻检查localStorage.getItem('theme') - 用户手动切换时，写入
localStorage并同步更新document.documentElement类名 - 不要覆盖系统偏好——保留一个「恢复默认」按钮，点击后删掉 localStorage 项，再重新 matchMedia
- 注意 Safari 私密模式下
localStorage可能被禁用，需加 try/catch 回退到内存状态
最常被忽略的是：暗黑模式不只是改背景和文字色，还涉及表单焦点框、阴影强度、border contrast ratio、甚至动画 easing（暗色下高对比动效更刺眼）。这些没法靠一个 media query 解决，得拆成可配置的主题层。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
