Excalidraw如何支持Dark Mode暗黑模式显示？
Excalidraw 如何实现自然流畅的暗黑模式体验？
在深夜调试架构图、凌晨撰写技术方案，或是昏暗会议室中进行头脑风暴时，你是否曾被某个刺眼的白底应用“闪到眼睛”？这种体验在传统白板工具中尤为常见——明亮的背景像一盏灯，在低光环境下显得格格不入。而 Excalidraw 却能在打开的一瞬间，悄然切换为柔和的深色界面，仿佛它早已知道你现在需要的是安静与专注。
这背后，正是其对暗黑模式（Dark Mode）的深度支持。但别误会，这并非简单的颜色反转或后期补丁，而是一套贯穿设计、渲染与状态管理的系统级解决方案。它的价值不仅在于“看起来更酷”，更在于如何在保持手绘风格艺术感的同时，确保信息可读、视觉舒适，并响应用户的每一个偏好选择。
Excalidraw 实现暗黑模式的核心思路可以归结为三个关键词：感知、解耦、适配。
首先是“感知”。现代浏览器提供了一个强大的 API ——window.matchMedia('(prefers-color-scheme: dark)')，它能直接读取操作系统级别的外观设置。当你在 macOS 中开启深色外观，或在 Windows 设置里启用暗色主题时，这个媒体查询就会返回true。Excalidraw 在页面加载初期就检查这一状态：
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;但这只是起点。真正聪明的地方在于，它并不完全依赖系统设定。用户可能希望强制使用亮色模式，哪怕系统是暗的；也可能想让应用“跟随系统”，动态变化。为此，Excalidraw 引入了三层主题逻辑：light、dark和system。这些选项通过 UI 菜单暴露给用户，选择后会持久化存储在localStorage中：
localStorage.setItem('app-theme', 'dark');这样一来，下次访问时即使网络离线，也能还原用户的偏好。更重要的是，当系统主题发生变化（比如从白天切换到夜间），页面还能实时响应：
window.matchMedia('(prefers-color-scheme: dark)') .addEventListener('change', e => { if (getCurrentTheme() === 'system') { applyTheme(e.matches ? 'dark' : 'light'); } });整个过程无需刷新，界面平滑过渡，体验近乎原生应用。
那么样式层面是如何配合的？答案是 CSS 自定义属性（CSS Variables）。Excalidraw 没有为每种主题写两套独立的 CSS 文件，而是采用变量驱动的方式统一管理颜色体系：
:root { --color-bg: #ffffff; --color-text: #000000; --color-panel: #f3f3f3; --color-border: #e0e0e0; } @media (prefers-color-scheme: dark) { :root { --color-bg: #121212; --color-text: #e0e0e0; --color-panel: #1e1e1e; --color-border: #383838; } }这种方式的好处显而易见：结构清晰、维护成本低，且能与 JavaScript 无缝协作。所有组件只需引用这些变量，就能自动适应当前主题。例如一个面板的样式可能是这样的：
.panel { background: var(--color-panel); color: var(--color-text); border: 1px solid var(--color-border); }无需任何条件判断，一切由浏览器自动完成。
当然，如果仅靠媒体查询还不够灵活——比如用户手动选择了“暗色”，但系统仍是亮色。这时就需要.theme-dark类来强制覆盖：
.theme-dark { --color-bg: #121212; --color-text: #e0e0e0; /* 其他变量... */ }JavaScript 根据当前设置决定是否向<html>添加该类名：
document.documentElement.classList.toggle('theme-dark', isDarkTheme);这种“媒体查询 + 类名控制”的双重机制，既保证了开箱即用的智能适配，又保留了用户自定义的自由度，堪称现代 Web 主题系统的典范。
但真正的挑战才刚刚开始：如何让那些标志性的“手绘风”线条和图形，在深色背景下依然清晰可辨？
要知道，Excalidraw 的视觉魅力源自 Rough.js —— 一个模拟真实笔触抖动效果的绘图库。它通过算法扰动路径坐标，在 Canvas 上生成看似随意却富有生命力的线条。然而，这种艺术化渲染在暗黑模式下面临新的考验：浅色线条在深色画布上容易发虚，填充区域可能因对比度过高而显得突兀，阴影和模糊效果也更容易失真。
解决方案不是简单地把黑色变白色，而是建立一套主题感知的渲染策略。
首先，颜色映射不再是硬编码，而是集中管理在一个配置对象中：
function getThemeColor(key, theme) { const colorMap = { background: { light: '#fff', dark: '#121212' }, stroke: { light: '#000', dark: '#e0e0e0' }, fill: { light: '#fff', dark: '#1a1a1a' }, text: { light: '#000', dark: '#fff' } }; return colorMap[key]?.[theme] || colorMap[key]['light']; }每次绘制图形时，都会根据当前主题动态获取对应的颜色值：
const rc = rough.canvas(canvas); rc.line(x1, y1, x2, y2, { stroke: getThemeColor('stroke', currentTheme), strokeWidth: currentTheme === 'dark' ? 1.5 : 1, roughness: currentTheme === 'dark' ? 2.5 : 1.4 });注意到没有？除了颜色，连线宽和粗糙度都做了微调。因为在深色背景下，细线更容易“融化”进背景中，适当加粗和增加扰动幅度，反而能让线条更具存在感。这是一种典型的“功能性美学”——形式服务于功能，而非牺牲可读性去追求一致。
文本处理更是如此。所有文字默认使用无衬线字体（如 Inter 或 SF Pro），字号不低于 14px，并启用抗锯齿优化。即便是在 OLED 屏幕上，浅色文字也不会出现边缘发虚的问题。团队甚至避免使用纯黑（#000000）作为背景，转而采用接近黑的深灰（如#121212），这样既能减少“死黑”带来的视觉压迫感，又能提升层次细节，尤其在投影演示时表现更佳。
整个主题系统的运行流程可以用一个简明的数据流概括：
[用户操作 / 系统变更] ↓ 读取 localStorage 或 matchMedia ↓ 计算实际应使用的主题（light/dark） ↓ 更新 DOM class 并触发 CSS 变量生效 ↓ Canvas 渲染器读取主题状态，调整绘图参数 ↓ 输出适配后的手绘图表这个流程高效且低侵入，切换主题几乎无延迟，也不会引发全图重绘。对于协作场景，虽然个人主题偏好不会同步给他人（毕竟每个人的眼睛需求不同），但可以通过 URL 参数传递初始主题，比如?theme=dark，方便会议主持人统一展示风格。
从工程角度看，这套设计体现了几个值得借鉴的最佳实践：
- 渐进式增强：即使浏览器不支持
prefers-color-scheme，应用仍可正常运行，仅失去自动检测能力； - 性能优先：主题切换只涉及少量 DOM 操作和变量更新，不影响核心绘图性能；
- 可扩展性强：基于变量和配置的设计，未来可轻松拓展出高对比度模式、色盲友好模式等辅助功能；
- 用户体验至上：允许用户覆盖系统设置，真正把控制权交还给使用者。
事实上，Excalidraw 对暗黑模式的支持早已超越了“功能实现”的范畴。它解决的不只是“晚上看不清”的问题，更是关于全天候可用性的思考。程序员可以在深夜调试架构图时不被打扰，设计师能在昏暗灯光下长时间创作，演讲者可在暗色环境中自信展示——这一切的背后，是产品对真实使用场景的深刻理解。
更难得的是，它没有因为引入暗黑模式而牺牲一丝一毫的手绘质感。无论是亮色还是深色主题，线条依旧自然，色彩依旧克制，整体风格始终如一。这种“不变中的变化”，恰恰是最难做到的平衡。
今天，越来越多的应用开始添加暗黑模式，但很多仍停留在表面：一键反色、图标缺失、对比度失控……而 Excalidraw 提供了一个范本——好的主题系统不是附加功能，而是从第一天起就融入 DNA 的设计哲学。
当你下次打开一个网页工具，发现它已经默默变成了你喜欢的样子，请记得，那背后可能是整整一套关于感知、解耦与适配的精密工程。而 Excalidraw 正是以其极简却不简单的姿态，告诉我们：真正的优雅，往往藏在最不起眼的细节里。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考