Django Debug Toolbar中暗黑模式与Pygments语法高亮的兼容性问题解析

在Django开发过程中，Django Debug Toolbar是开发者常用的调试工具之一。近期社区反馈了一个关于暗黑模式与Pygments语法高亮显示冲突的问题，本文将深入分析问题原因并提供解决方案。

问题现象

当用户启用系统级暗黑模式或手动切换Debug Toolbar的暗黑主题时，Pygments生成的语法高亮显示会出现异常。主要表现为代码块的背景色与文字颜色对比度不足，导致代码可读性下降。

技术背景

Pygments是Python生态中广泛使用的语法高亮工具，它通过生成带有特定CSS类名的HTML元素来实现代码着色。而Django Debug Toolbar的主题切换功能通过修改HTML元素的data-theme属性和应用不同的CSS样式表来实现。

问题根源分析

经过代码审查，发现当前实现存在两个关键问题：

1. CSS加载机制缺陷：现有的CSS样式表需要被加载两次——一次用于响应系统偏好设置（通过媒体查询），另一次用于处理用户手动切换主题的情况。

2. 初始状态检测缺失：工具栏初始化时没有检测系统的颜色方案偏好，仅依赖本地存储中的用户设置。

解决方案

方案一：CSS结构调整

建议修改CSS文件结构，将主题相关的样式统一处理。核心修改包括：

/* 合并暗黑模式和亮色模式的样式 */
[data-theme="dark"] .highlight {
    background-color: #2d2d2d;
    color: #f8f8f2;
}

/* 保留媒体查询作为回退 */
@media (prefers-color-scheme: dark) {
    .highlight {
        background-color: #2d2d2d;
        color: #f8f8f2;
    }
}

方案二：JavaScript逻辑增强

改进主题初始化逻辑，增加对系统颜色方案的检测：

// 初始化时检测系统偏好
const userTheme = localStorage.getItem("djdt.user-theme");
if (userTheme !== null) {
    djDebug.setAttribute("data-theme", userTheme);
} else if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
    djDebug.setAttribute("data-theme", "dark")
}

方案三：参考Django Admin的实现

Django Admin提供了完善的主题切换机制，值得借鉴的特点包括：

• 三态循环切换（自动/亮色/暗黑）
• 优雅的过渡动画
• 完善的本地存储管理

实施建议

对于开发者而言，建议按照以下步骤解决问题：

1. 首先应用CSS结构调整（方案一），这是最直接的修复方式
2. 随后增强JavaScript逻辑（方案二），提升用户体验
3. 长期可以考虑完整移植Django Admin的主题机制（方案三）

兼容性考虑

在实现过程中需要注意：

• 保持对旧版浏览器的兼容性
• 确保Pygments生成的所有语法元素都能正确响应主题变化
• 在CSS中使用适当的颜色对比度，确保可访问性

通过以上改进，可以完美解决暗黑模式下的语法高亮显示问题，同时为用户提供更一致的主题体验。