Dashy 主题定制完全指南从内置主题到自定义 CSS 变量体系【免费下载链接】dashy A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!项目地址: https://gitcode.com/GitHub_Trending/da/dashyDashy 作为一款可自托管的个人仪表盘把外观可定制做到了配置文件与 UI 双通道驱动默认自带 40 套内置主题同时支持通过conf.yml、外部样式表、UI 调色板三种方式注入自定义样式。本文以官方 Theming 文档为主体结合仓库源码src/utils/Theming.js、src/styles/color-palette.scss、src/styles/color-themes.scss 等深入讲解主题切换的底层机制、自定义主题的两种路径、CSS 变量完整参考与调试方法。读完本文你将能独立打造一套属于自己仪表盘的专属主题并理解其与配置、源码之间的全部关联。主题切换的工作原理data-theme CSS 变量Dashy 的主题机制极简切换主题 在根 DOM 元素上更换data-theme属性值所有颜色与样式均由 CSS 变量承载CSS 通过属性选择器html[data-themexxx]精确命中对应主题块。这一逻辑在 src/utils/Theming.js 的applyTheme(theme, appConfig)函数中有完整实现其处理分支如下主题为default调用resetDom()移除data-theme属性并删除外部样式表节点主题在「内置主题 appConfig.cssThemes自定义主题」列表中resetDom()后设置html.setAttribute(data-theme, theme)主题命中appConfig.externalStyleSheet声明的外部样式表以link标签动态注入user-defined-stylesheet样式表无论走哪条分支最后都会调用applyCustomVars(theme, appConfig)把该主题对应的customColors以 CSS 变量的形式写入根元素内联样式。而applyTheme的调用点位于 src/App.vue通过effectiveTheme计算属性监听主题变化immediate: true保证应用启动时就完成首次应用。effectiveTheme的取值优先级为「路由元信息声明的主题如 404 页 用户当前选中的主题」。UI 上的主题下拉框src/components/Settings/ThemeSelector.vue会列出两类主题内置主题定义于 src/utils/config/defaults.js 的builtInThemes数组加上你在appConfig.cssThemes中自定义的主题。选择后html[data-thememy-theme]{}块内的样式即被应用。设置默认主题要让实例在首次加载时就应用某个主题在配置文件中设置appConfig.theme即可若希望跟随操作系统浅色/深色偏好则改用dayTheme与nightThemeappConfig: theme: dracula # 固定默认主题 # dayTheme: minimal-light # OS 为浅色模式时生效 # nightTheme: minimal-dark # OS 为深色模式时生效从 src/store.js 的themegetter 可以看到完整取值链(prefersDark ? nightTheme : dayTheme) || configTheme || defaultTheme即dayTheme/nightTheme会覆盖theme而theme又覆盖内置兜底值default。对应的 schema 定义在 src/utils/config/ConfigSchema.json其中明确注释了dayTheme/nightTheme「在首次加载时覆盖 theme」。内置主题一览builtInThemes数组src/utils/config/defaults.js收录了全部内置主题包括default、glass、callisto、material、material-dark、dashy-docs、colorful、dracula、one-dark、lissy、cherry-blossom、nord-frost、nord、argon、fallout、whimsy、oblivion、adventure、crayola、deep-ocean、minimal-dark、minimal-light、thebe、matrix、matrix-red、color-block、raspberry-jam、bee、tiger、glow、glow-dark、vaporware、cyberpunk、material-original、material-dark-original、high-contrast-dark、high-contrast-light、adventure-basic、basic、tama、neomorphic、glass-2、night-bat、tokyo-night、gruvbox、rose-pine、parchment、aurora、zinc、solarized-dark、solarized-light、brutalist、midnight、catppuccin共 54 个含default。每个主题的样式定义分散在 src/styles/themes/ 目录下的 SCSS 分部文件中并由 src/styles/color-themes.scss 按固定顺序统一import进单个 CSS 产物。每个分部文件的形态如 src/styles/themes/_dracula.scss 所示——一个html[data-themedracula]块内部覆盖 CSS 变量甚至可以附带结构微调如border: 1px solid var(--primary)与针对nth-child的循环取色逻辑。内置主题可随时从 UI 下拉菜单切换无需修改任何配置。添加自定义主题两种路径Option 1纯颜色主题定义在conf.yml这是最快上手的方式适合只想换配色、不想写完整 CSS 的场景。把主题名登记到cssThemes让它在下拉框出现再把颜色写进customColorsappConfig: theme: mytheme cssThemes: [mytheme] customColors: mytheme: primary: #ff6b6b background: #1a1a2e background-darker: #0f0f1e重载 Dashy 后mytheme就会出现在主题下拉框中。customColors中可写入后文 CSS 变量参考中的任意变量不限于上述三个。其底层实现见 src/utils/Theming.js 的applyCustomVars它会合并appConfig.customColors与 localStorage 中的用户本地调色localStorage 优先级更高随后通过html().style.setProperty(-- k, v)把每个变量写入根元素内联样式切换主题前还会用mainCssVars与全部已知变量名做一次清理避免上一个主题的残留变量污染新主题。Option 2完整 CSS 文件推荐用于字体/背景/布局微调当你要定制的不只是颜色——比如字体、背景图、间距布局——或者需要一个可在多实例间复用的可移植文件就应使用外部样式表方案。把 CSS 文件放进你挂载conf.yml的目录通常是./user-data/。Dashy 会把该目录作为静态资源暴露在站点根路径下因此样式表可直接通过/mytheme.css访问/* user-data/mytheme.css */ html[data-thememytheme] { --primary: #ff6b6b; --background: #1a1a2e; --background-darker: #0f0f1e; /* 这个块内的任何样式只在 mytheme 激活时生效 */ }然后在配置中接线appConfig: theme: mytheme cssThemes: [mytheme] externalStyleSheet: /mytheme.cssexternalStyleSheet也接受完整https://URL托管在 CDN 或仓库中并且支持传数组一次加载多份样式表详见下文「加载外部样式表」。补充说明仓库里还保留了一个传统的自定义主题入口 src/styles/user-defined-themes.scss其中注释给出了示例语法html[data-thememy-theme] { --primary: #00CCB4; ... }同样要求主题名登记到appConfig.cssThemes。从源码看主题定义既可以走「编译期 SCSS 注入」也可以走「运行时 CSS 文件注入」两种形态殊途同归。修改主题颜色UI 调色板与配置文件主题颜色有两条修改通道UI 通道主题下拉框右侧的调色板按钮ThemeSelector.vue 中由config-color-palette.svg图标触发打开 CustomThemeMaker 调色板可直接对当前主题的变量取色修改配置通道直接在conf.yml的appConfig.customColors下写变量值。重要行为说明通过 UI 修改的颜色默认只保存在本地localStorage对应 key 为customColors见 defaults.js 的localStorageKeys。若要全局生效点击「Export」按钮导出变量名与色值再备份或写入配置文件自定义颜色是相对于当前基础主题保存的。如果你设置了自定义颜色后又切换主题这些设置不再生效——但改动不会丢失切回原主题时会重新应用在conf.yml中书写时注意包含特殊字符的键或值必须用引号包裹YAML 语法要求。配置文件中customColors的典型写法appConfig: customColors: oblivion: primary: #75efff background: #2a3647 dracula: primary: #8be9fd从源码看UI 调色板的默认色板swatches与主题配置器首屏展示的核心变量mainCssVars: [primary, foreground, background, background-darker]均定义在 src/utils/config/defaults.js。在 UI 中编写自定义 CSS自定义 CSS 可以直接在界面里开发、测试并应用打开顶部选项面板内的 Config 菜单扳手图标进入 Custom Styles 标签页编辑即可。这些内容与 localStorage 中的appConfig.customCss相关联因此跨实例迁移时需自行记录导出。样式也可直接写入配置文件中的appConfig.customCss属性但 CSS 量较大时会很快变得难以维护。注意UI 注入的 CSS 与配置文件注入走的是同一套执行路径——src/App.vue 的injectCustomStyles/applyCustomStyles会在mounted()时把customCss清洗剔除/style等标签注入攻击后以style节点追加到head。页面专属样式当仪表盘包含多个子页面时可以让样式只作用于特定页面。body内最顶层的元素会携带一个与当前子页面同名的 class——通常是页面名全小写、空格替换为连字符的形态具体名字可用开发者工具自行确认也可参考 src/App.vue 中subPageClassName的来源。例如页面名为 CFT Toolbox想只针对该页的.item元素加边框.cft-toolbox .item { border: 4px solid yellow; }加载外部样式表appConfig.externalStyleSheet用于加载本地或远程 CDN 的样式表接受单个字符串或字符串数组也可用于加载自定义字体样式表必须是 CSS 格式如https://fonts.googleapis.com/css2?familyCutiveMono这类字体 API。其运行时代理由 src/App.vue 的applyCustomStyles负责先移除带data-external-source标记的旧样式表节点避免重复再为每个 URL 创建link relstylesheetURL 仅接受http或/开头否则触发ErrorHandler。appConfig: externalStyleSheet: https://example.com/my-stylesheet.cssappConfig: externalStyleSheet: [/themes/my-theme-1.css, /themes/my-theme-2.css]顺带一提外部样式表也会出现在主题下拉框中 src/utils/Theming.js 的getExternalThemes会把字符串形式的样式表命名为「External Stylesheet」、数组形式命名为「External Stylesheet 1/2/...」并加入可选主题列表选中时即动态注入该样式表。硬编码 Section / Item 颜色部分 UI 组件在配置文件中支持强制颜色选项不受当前主题影响颜色须使用十六进制如#fff或 HTML 颜色名如red。支持以下属性section.color— 指定 section 的自定义颜色item.color— 指定 item 的文字与图标颜色item.backgroundColor— 指定 item 图标的背景色字体与排版Typography应用内置的核心字体位于./src/assets/fonts/如 Raleway、PT Mono、Inconsolata主题用到的可选字体存放在./public/fonts/新增字体应放这里Docker 部署时用 volume 把宿主机目录映射到容器内该路径管理会更方便性能优化未被当前主题使用的字体不会在页面加载时被请求只在需要时才按需加载。因此多个主题使用不同字型也不会对性能造成负面影响。修改浏览器地址栏 / 标签页颜色部分浏览器支持通过主题色给地址栏、任务切换卡片标题栏着色。设置pageInfo.color为任意合法 CSS 颜色即可如#ff00a7、rebeccapurple、rgb(40, 60, 120)。注意浏览器支持仍有限Android Chrome、Safari iOS 15 及部分新版移动端 Chromium已安装 PWA 的情况下此设置不生效更多页面级浏览器与 UI 选项参见 Pages and Sections。CSS 变量完整参考Dashy 的所有颜色及其他样式值边框、圆角、阴影等都以CSS 变量形式管理——这是整个主题体系的基石改一处全局联动。变量全集定义于 src/styles/color-palette.scss各主题对这些变量的覆盖则汇总于 src/styles/color-themes.scss及其themes/分部文件。CSS 变量用法示例:root { --background: #fff; } body { background-color: var(--background); }顶层变量创建主题的最低要求以下变量构成一个主题的全部必需项其余变量默认从它们继承可按需覆盖--primary— 应用主色用于标题、文字、强调色及其他特性--background— 应用背景色--background-darker— 次级背景色通常更深用于导航栏、section 填充、页脚等--curve-factor— 全局圆角半径单位px默认5px--dimming-factor— 非活跃元素的透明度取值0不可见到1正常默认0.7定向颜色变量精准控制具体组件全部可选默认继承自顶层变量--heading-text-color— 页面标题与副标题文字颜色默认--primary--nav-link-text-color— 导航栏链接文字颜色默认--primary--nav-link-background-color— 导航栏链接背景色--nav-link-text-color-hover— 导航栏链接悬停文字颜色默认--primary--nav-link-background-color-hover— 导航栏链接悬停背景色--nav-link-border-color— 导航栏链接边框颜色默认transparent--nav-link-border-color-hover— 导航栏链接悬停边框颜色默认--primary--search-container-background— 搜索栏所在容器背景默认--background-darker--search-field-background— 搜索框填充色默认--background--settings-background— 快速设置面板背景默认--background--settings-text-color— 快速设置文字与图标颜色默认--primary--footer-text-color— 页脚文字颜色默认--medium-grey--footer-text-color-link— 页脚内超链接颜色默认--primary--item-text-color— item 文字与图标颜色默认--primary--item-group-outer-background— section 外部背景含 section 头部默认--primary--item-group-background— item 组内部背景默认#0b1021cc半透明黑--item-group-heading-text-color— section 标题文字颜色默认--item-group-background--item-group-heading-text-color-hover— section 标题悬停文字颜色默认--background--config-code-background— 配置菜单 JSON 编辑器背景默认#fff--config-code-color— JSON 编辑器中未高亮代码的文字颜色默认--background--config-settings-color— 配置/设置弹窗背景默认--primary--config-settings-background— 设置容器内文字颜色默认--background-darker--scroll-bar-color— 滚动条滑块颜色默认--primary--scroll-bar-background— 滚动条空白区颜色默认--background-darker--highlight-background— 文本高亮填充色默认--primary--highlight-color— 选中/高亮文本颜色默认--background--toast-background— toast 弹窗背景默认--primary--toast-color— toast 内文字、图标与边框颜色默认--background--welcome-popup-background— 首次加载欢迎弹窗背景默认--background-darker--welcome-popup-text-color— 欢迎弹窗文字颜色默认--primary--side-bar-background— Workspace 视图侧边栏背景默认--background-darker--side-bar-color— 侧边栏图标与文字颜色默认--primary--status-check-tooltip-background— 状态检查 tooltip 背景默认--background-darker--status-check-tooltip-color— 状态检查 tooltip 文字颜色默认--primary--code-editor-color— 原始代码编辑器文字颜色默认--black--code-editor-background— 原始代码编辑器背景默认--white--context-menu-color— item 右键菜单文字颜色默认--primary--context-menu-background— 右键菜单背景默认--background--context-menu-secondary-color— 右键菜单边框与描边颜色默认--background-darker非颜色变量--outline-color— 聚焦/选中元素的描边颜色--curve-factor-navbar— 导航栏圆角通常大于--curve-factor--scroll-bar-width— 横竖向滚动条宽度如8px--item-group-padding— section 内边距决定描边宽度如5px--item-shadow— item 阴影如1px 1px 2px #130f23--item-hover-shadow— item 悬停阴影如1px 2px 4px #373737--item-icon-transform— 作用于 item 图标的transform属性如drop-shadow(2px 4px 6px var(--transparent-50)) saturate(0.65)--item-icon-transform-hover— 同上但仅在 item 悬停时生效如drop-shadow(4px 8px 3px var(--transparent-50)) saturate(2)--item-group-shadow— item 组/section 阴影默认--item-shadow--settings-container-shadow— 设置容器阴影如none动作颜色Action Colors这类颜色表达语义意图通常不做修改但你可以按需覆盖--info— 信息色通常为蓝 /#04e4f4--success— 成功色通常为绿 /#20e253--warning— 警告色通常为黄 /#f6f000--danger— 错误/危险色通常为红 /#f80363--neutral— 中性色通常为灰 /#272f4d--white— 纯白 /#fff--black— 纯黑 /#000用浏览器开发者工具调试主题变量在 color-palette.scss 之外你还可以直接借助浏览器开发者工具定位任意元素使用的变量并实时预览改动按F12或 选项 → 更多 → 开发者工具打开开发者工具在 Elements 标签页点击左上角的元素选择器图标悬停并点击页面上任意 DOM 元素右侧 CSS 面板会列出该元素的所有样式含 CSS 变量点击变量可查看其继承来源点击颜色方块可直接修改颜色并即时预览效果。小结选择你的定制路径需求推荐方案相关配置项只换配色快速生效conf.yml中customColorsappConfig.customColors字体/背景/布局等深度定制完整 CSS 文件 externalStyleSheetappConfig.externalStyleSheet临时调试配色UI 调色板仅本地生效可导出localStoragecustomColors一次性注入少量样式UI Custom Styles 标签页appConfig.customCss固定默认主题配置文件声明appConfig.theme/dayTheme/nightTheme理解data-theme属性选择器与 CSS 变量继承链这两条主线后Dashy 主题体系对你就不再是黑盒——无论是复刻一套 Dracula 风格参考 src/styles/themes/_dracula.scss还是构建完全属于自己的配色都能在配置文件与源码之间自如游走。【免费下载链接】dashy A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!项目地址: https://gitcode.com/GitHub_Trending/da/dashy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
