Excalidraw 在 Sphinx 文档中实现主题自动切换的技术方案

背景介绍

Excalidraw 是一款流行的开源白板工具，常用于绘制技术图表和架构图。许多开发者喜欢在项目文档中使用 Excalidraw 来创建示意图。当文档系统支持深色/浅色主题切换时，如何让 Excalidraw 绘制的图表也能自动适应主题变化，成为一个值得探讨的技术问题。

核心挑战

在 Sphinx 文档系统中使用 PyData 主题时，文档可以支持深色/浅色模式的切换。但 Excalidraw 绘制的静态图片无法自动响应这种主题变化，这会导致以下问题：

1. 浅色主题下，深色背景的图表可能不协调
2. 深色主题下，浅色背景的图表可能过于刺眼
3. 手动维护两套图表增加工作量

解决方案

方案一：动态嵌入 Excalidraw 实例

最理想的解决方案是将 Excalidraw 实例直接嵌入到文档中，通过 JavaScript API 监听主题变化并动态调整：

1. 在 Sphinx 文档中嵌入 Excalidraw iframe 或使用 npm 包
2. 监听文档主题切换事件
3. 调用 Excalidraw 的 API 切换主题

这种方法需要文档系统支持 JavaScript 交互，并能正确处理 iframe 或 npm 包的引入。

方案二：双版本静态图片切换

对于不支持动态嵌入的场景，可以采用生成两套图表的方案：

1. 分别导出浅色和深色主题的图表
2. 使用 CSS 或 JavaScript 根据当前主题显示对应版本
3. 通过类名或数据属性控制显示逻辑

这种方法虽然需要维护两套资源，但兼容性更好，适用于各种静态文档系统。

实现细节

动态嵌入的技术要点

1. 使用 Excalidraw 的 theme 常量控制主题
2. 监听文档的 prefers-color-scheme 变化
3. 处理跨域和安全策略问题

静态切换的技术要点

1. 图片命名规范建议（如添加 _dark/_light 后缀）
2. 使用 picture 元素或 JavaScript 切换逻辑
3. 考虑懒加载和性能优化

最佳实践建议

1. 对于复杂文档系统，优先考虑动态嵌入方案
2. 简单项目可使用静态切换方案，注意保持两套资源的同步
3. 在 Excalidraw 中设计图表时，考虑两种主题下的可读性
4. 测试不同主题下的显示效果，确保对比度足够

总结

Excalidraw 图表与文档主题的自动适配是一个涉及前端交互和资源管理的综合问题。开发者可以根据项目需求和文档系统的能力，选择最适合的实施方案。随着 Excalidraw API 的不断完善，未来可能会有更简便的集成方式出现。