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

问题背景

Django Debug Toolbar作为Django开发者常用的调试工具，近期引入了暗黑模式支持。但在实际使用中发现，当启用暗黑模式时，与Pygments语法高亮功能存在显示冲突，导致代码高亮区域在暗色背景下出现不协调的显示效果。

技术原理分析

这个问题本质上源于CSS样式的优先级和加载顺序问题。Django Debug Toolbar通过两种方式实现暗黑模式：

1. 通过媒体查询@media (prefers-color-scheme: dark)响应系统级别的暗黑模式设置
2. 通过JavaScript实现的用户手动切换功能

而Pygments生成的语法高亮CSS是静态的，不会根据主题变化自动调整。当暗黑模式激活时，Pygments生成的浅色背景代码块在深色背景下显得格外突兀。

解决方案

核心解决思路

1. 双重CSS加载方案：需要为Pygments语法高亮准备两套CSS样式，分别对应亮色和暗色主题
2. 动态主题检测：改进JavaScript代码，使其能够检测系统级别的主题偏好

具体实现方案

对于Django Debug Toolbar的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")
}

对于CSS部分，需要为Pygments语法高亮准备两套样式，并通过主题选择器进行切换：

/* 亮色主题下的Pygments样式 */
[data-theme="light"] .highlight {
    background: #f8f8f8;
    color: #333;
}

/* 暗色主题下的Pygments样式 */
[data-theme="dark"] .highlight {
    background: #2d2d2d;
    color: #f8f8f8;
}

进阶优化建议

1. 主题循环切换：参考Django admin的主题切换实现，提供亮色/暗色/系统默认三种状态的循环切换
2. 主题一致性：确保所有UI元素(包括Pygments高亮)在不同主题下都保持协调的视觉效果
3. 预置主题包：考虑集成流行的主题方案，如Dracula主题，提供开箱即用的美观配色

实施注意事项

1. 测试时需要确保已安装Pygments库，否则语法高亮功能不会生效
2. 修改后需清除浏览器缓存进行测试
3. 对于自定义模板，需要确保同时更新相关CSS和JavaScript文件

通过以上改进，可以解决Django Debug Toolbar暗黑模式与Pygments语法高亮的兼容性问题，为用户提供更加一致的视觉体验。