Wekan 深色模式（Dark Mode）全解析：内置 dark 系列主题与系统级深色方案
Wekan 深色模式Dark Mode全解析内置 dark 系列主题与系统级深色方案【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekanWekan基于 Meteor 构建的开源看板应用原生内置了完整的深色主题体系在dark分类下提供 midnight、dark、moderndark、exodark、cleandark 五款固定深色设计同时通过--theme-accent等 CSS 变量把主题色扩散到看板外的全局界面元素。本文以 Dark-Mode.md 为骨架结合 Theme.md 的设计文档与源码实现完整讲解 Wekan 深色模式的两条路径——应用内置深色主题与操作系统/浏览器层面的全局深色方案并给出主题分类、配色映射、存储模型、校验机制与扩展清单读完可直接在实例中切换深色主题或新增一款深色配色。一、Wekan 内置深色主题dark 分类的 5 款配色与许多仅靠浏览器插件硬反转页面颜色的方案不同Wekan 的深色模式是原生内置的每款深色主题都是一套手工调校的.board-color-nameCSS 规则覆盖看板画布、列表、卡片、侧边栏、按钮、滚动条等完整表面而不是简单的颜色反相。根据 themeCategories.js 中的分类定义Wekan 的全部主题色被划分为四个类别其中dark深色分类包含 5 款固定设计分类主题色是否允许自定义颜色flatbelize、nephritis、pomegranate、pumpkin、wisteria、moderatepink、strongcyan、limegreen、natural允许 1 个单一强调色clearclearblue、cleargreen、clearorange、clearpink、clearpurple、clearred允许 2 个渐变色 slidedarkmidnight、dark、moderndark、exodark、cleandark不允许固定设计specialrelax、corteza、appleglasspastel、modern、cleanlight不允许固定设计dark 与 special 分类被设计为手工调校的多色设计贸然注入一个自定义颜色会破坏对比度与可读性因此这两类固定用户只能选择命名主题无法自定义颜色——这是与 flat/clear 分类最核心的区别。1.1 五款深色主题的配色映射每款深色主题在 boardColors.css 中定义了完整的 CSS 变量族。以midnight为例boardColors.css.board-color-midnight { --board-theme-accent: #2c3e50; --board-theme-dark: #233240; --board-theme-hover: #3a5169; --board-theme-emphasis: #503e2c; --board-theme-emphasis-hover: #483828; --board-theme-emphasis-close: #403223; --board-theme-checklist-bg: #d2dae2; --board-theme-selected-bg: #e6ecf1; --board-theme-selected-hover-bg: #f8f9fb; --board-theme-bright: #476582; --board-theme-canvas-scrollbar: #2c3e50f2; --board-theme-sidebar-scrollbar: #2c3e50f2; }而dark主题则使用独立的规则族boardColors.css 的 THEME - Dark 区块其关键颜色为样式元素颜色值顶栏#header、快速访问栏#header-quick-access、spinner#2c3e51主按钮button[typesubmit].primary、侧边栏按钮#233241hover 态弹层列表项、侧边栏按钮、侧边栏列表#3a516a当前导航项下边框#3a516a强调按钮emphasis背景#513f2c迷你卡片minicard白色 90% 透明背景 圆角 阴影已选中卡片左边界#2c3e513px 实线其余三款深色主题的强调色accent在 themeAccents.js 中有集中登记midnight: #2c3e50, dark: #2c3e51, moderndark: #2a2a2a, exodark: #222, cleandark: #2E2E39,也就是说从最接近蓝黑色办公感的midnight#2c3e50到近似纯黑的exodark#222Wekan 提供了一条完整的深色渐变光谱用户可按团队偏好或演示场景选择。1.2 深色主题如何作用于全局界面从源码结构看Wekan 的主题机制是内外有别的看板页面内部由board-color-name类驱动看板之外的应用外壳管理面板左菜单、保存按钮、表格页控件等则统一读取一个 CSS 变量--theme-accent。themeAccents.js 的注释说明了这一设计意图该文件维护每个命名主题的强调色映射表无论当前生效的是用户自己的覆盖、看板颜色还是站点主题其强调色都会发布为--theme-accent所有读取该变量的界面元素随之联动。activeAccent(color, customColors)决定最终发布的值自定义颜色永远优先用户自行选择覆盖主题的强调色否则回落到命名主题的默认强调色。对于dark分类由于不允许自定义颜色实际值就是上表所列的固定色值。该映射表与boardColors.css中的#header规则互为镜像并有专门测试守护——tests/themeAccents.test.cjs会解析该样式表一旦两处不一致测试即失败防止新增主题只改了 CSS 却悄悄回退到蓝色。二、如何切换深色主题实操Wekan 的深色主题有三个作用层级从弱到强依次为Theme.md站点主题site theme在管理面板 Admin Panel / Settings / Visibility / Change color 设置作为实例默认在多租户主机上组织的设置会覆盖实例级设置。用户全局覆盖users own override在 Member Settings成员设置/ Change Color 中选择作用于整个 UI——board-color-name会被施加到body/header 上。选择该主题的用户在任何地方都能看到深色界面。看板颜色board color在 Board Settings看板设置/ Change Color 中设置仅作用于该看板页面。看板自身的颜色优先于站点主题站点主题不在看板页生效但用户自己的全局覆盖依然生效——因为用户明确要求到处都用。因此要让整个 Wekan 界面变深色推荐路径是Member Settings成员设置→ Change Color → dark 分类 → 选择 midnight / dark / moderndark / exodark / cleandark 之一。2.1 Select Color 选择器的两级下拉交互Board Settings 与 Member Settings 共用同一个 Select Color 弹层Theme.md其交互骨架如下Category: [ flat ▼ ] - 1级下拉按 themeCategories 顺序 Theme: [ belize ▼ ] - 2级下拉所选分类下的主题色 (flat) Custom color: [ 颜色选择器] - 仅 flat 显示 (clear) Colors: [ 选择器 1] [ 选择器 2] - 仅 clear 显示 (dark/special) — 无自定义颜色控件 — [ 预览色块 ] [ 保存 ] [ 默认 / 取消设置 ]1 级下拉选分类2 级下拉随之刷新为该分类的主题列表颜色选择器使用原生input typecolor复用models/lib/contrastColor的isHexColor/toHex选择dark/special分类时颜色选择器控件整体隐藏预览色块实时展示命名主题或自定义颜色的效果Default / Unset看板场景回落实例默认成员场景清除全局覆盖。深色分类在 2 级下拉中按顺序展示 5 款主题themeCategories.jsdark: [midnight, dark, moderndark, exodark, cleandark],三、深色主题的存储模型与校验安全机制3.1 存储结构深色主题与其他主题一样把主题名与自定义颜色分开存储看板级board.color主题名board.customThemeColors: [String]#rrggbb数组flat 为 1 个、clear 为 2 个用户级profile.globalThemeColorprofile.globalThemeCustomColors: [String]一个自定义 flat/clear 主题因此表示为{ color: belize, customThemeColors: [#123456] }——命名主题决定 CSS 设计自定义颜色覆盖其强调色。清除customThemeColors即恢复该主题的出厂配色。对dark分类而言由于其customColorCount为 0存储层天然不会接受任何自定义颜色这也是固定设计在数据层的落地。3.2 服务端校验杜绝 CSS 注入自定义颜色最终会成为 CSS 值属于用户输入必须在服务端严格校验。themeCategories.js 的isValidCustomColors(color, customColors)强制执行三条规则const HEX_RE /^#[0-9a-fA-F]{6}$/; function isValidCustomColors(color, customColors) { const cat categoryOf(color); const count customColorCount(cat); if (count 0) return false; // dark/special/unknown: no custom colors if (!Array.isArray(customColors) || customColors.length ! count) return false; return customColors.every(c typeof c string HEX_RE.test(c)); }即命名颜色必须属于允许自定义颜色的分类flat/clear数组长度必须恰好等于该分类的配额每个条目必须是#rrggbb格式。board.setColor(color, custom)与setGlobalThemeColor(color, custom)两个方法会拒绝任何不满足条件的输入由于只有#rrggbb能通过不存在 CSS 注入面。dark/special 主题因为count 0直接返回 false从源头锁死自定义。3.3 主题色如何渲染到页面当自定义主题激活时globalThemeColor.js会在:root上设置--theme-accent/--theme-accent-2在看板内使用看板颜色否则使用用户全局覆盖并切换has-custom-theme-color/has-custom-theme-slidebody 类customTheme.css 消费这些变量为顶栏、主按钮、侧边栏按钮重新着色。对于深色主题无自定义色activeAccent直接返回命名主题的默认强调色--theme-accent同样被正确发布保证深色主题下管理面板按钮、左菜单高亮行等全局元素与看板保持一致的深色观感。四、系统级深色方案浏览器 / 邮件客户端 / 桌面OS 层面除了应用内置主题Dark-Mode.md 还汇总了在操作系统或浏览器层面强制全局深色的方案适用于只想让整个桌面统一变深色、包括 Wekan 在内的场景。这些方案作用于浏览器渲染层会把所有网页含 Wekan统一置为深色。4.1 桌面端 ChromeDark Mode ExtensionChrome 网上应用店的 Dark Mode for Chrome 扩展将包括 Wekan 在内的所有网页改为深色Decent - Dark Theme另一款深色主题扩展可按个人偏好选择。4.2 Firefox桌面与移动端Dark Mode WebextensionMozilla Add-ons 提供将包括 Wekan 在内的所有网页改为深色也可直接使用 Firefox 自带的深色主题there is dark themes, depends what someone likes——按个人喜好选择。4.3 Thunderbird 邮件客户端安装TT DeepDark - Dark Theme后还需手动配置文字与背景色点击Edit / Preferences / Display / Colors / FontColors将 Colors 的Text 设为 Grey灰色、Background 设为 Black黑色同时把Plain Text Messages 的 Color 设为 Black。该配置专门面向在 Thunderbird 中接收 Wekan 邮件通知的用户。4.4 Qubes OS 桌面通过系统外观设置启用全局深色Start / System Tools / Appearance / Styles中选择Adwaita-dark。4.5 Android M移动端Android M 系统提供系统级深色 UI 主题Finally Android M scores a new system-wide dark UI theme开启后系统各应用含 Web 浏览中的 Wekan会呈现深色外观。两种路径如何选应用内置深色主题路径一是 Wekan 原生、可控、配色协调的方案推荐团队使用系统/浏览器方案路径二适合全桌面统一深色的场景但颜色反转是通用算法可能不如原生深色主题精致。二者可叠加使用。五、给开发者如何新增一款深色主题若需在实例中扩展深色主题Theme.md 给出了三条扩展清单配合仓库内的守护测试可保证不出错登记颜色名把新颜色名加入 config/const.js 的ALLOWED_BOARD_COLORS数组该数组是合法颜色集合的唯一权威来源const.js归类在 models/lib/themeCategories.js 中把它加入正确的分类dark 分类示例dark: [midnight, dark, moderndark, exodark, cleandark]——tests/themeCategories.test.cjs会强制分类并集与ALLOWED_BOARD_COLORS完全相等漏登记即测试失败编写 CSS添加.board-color-name规则。若属 flat/clear 主题用--theme-accent[-1/-2]变量驱动强调色以免费获得自定义颜色支持dark/special 主题则直接写死色值无变量、无自定义色。提醒deep dark 主题属于 dark 分类customColorCount为 0因此新增时不需要也不允许提供自定义颜色通道。六、相关源码与文档索引主题文件说明主题分类权威定义models/lib/themeCategories.js四分类、isValidCustomColors校验、CUSTOM_COLOR_COUNT强调色映射models/lib/themeAccents.js--theme-accent的取值来源含全部 dark 色值合法颜色集合config/const.jsALLOWED_BOARD_COLORS与分类并集互为镜像主题 CSSclient/components/boards/boardColors.css各主题 CSS 变量族与 THEME - Dark 区块全局主题色应用client/components/main/customTheme.css消费--theme-accent重着色全局控件站点主题配置models/settings.jsthemeColor/themeCustomColors存储定义设计文档docs/Features/Theme/Theme.mdSelect Color 分类、存储、渲染与扩展清单相关文档docs/Features/Theme/Custom-CSS-themes.md自定义 CSS 主题进阶玩法核心结论回顾Wekan 的深色模式并非单一开关而是一套分层主题系统——dark 分类下 5 款固定深色主题由boardColors.css完整定义通过--theme-accent变量联动全局界面dark/special 分类拒绝自定义颜色以保可读性服务端isValidCustomColors校验杜绝 CSS 注入若需系统级深色可叠加 Chrome/Firefox 深色扩展、Thunderbird TT DeepDark、Qubes Adwaita-dark 或 Android M 深色主题。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考