ML4W 深度定制指南：基于 starter 模板打造属于自己的 Waybar 主题并一键切换

• 桌面应用

Waybar 是 Hyprland 桌面的状态栏核心组件，而 ML4W（The ML4W OS）在dotfiles/.config/waybar/themes/下为它设计了一套多主题、可热切换的扩展架构。本指南以ml4w-minimal主题配套的 README 为主线，讲解如何基于 starter 模板复制出属于自己的主题、定义主题名、通过内置切换器（SUPER+CTRL+T）在多个主题间来回切换，以及如何启用、禁用和重排 Waybar 模块——全程不碰源码，只靠复制与配置即可完成。读完你既能掌握一套可复用的"自定义 Waybar 主题"标准流程，也能理解其背后的脚本与配置文件是如何协作的。

一、主题机制全景：一个 Waybar 主题目录由哪些文件构成

ML4W 将每一个 Waybar 主题封装为一个独立文件夹，统一放置在~/.config/waybar/themes/下。以本仓库中的 ml4w-minimal 主题为例，一个完整的主题目录通常由三个核心文件组成：

其中config.sh是全仓库所有主题的"命名约定"，内容极其精简：

#!/bin/bash theme_name="ML4W Minimal"

这个theme_name会被主题切换脚本读取并展示在启动器列表中（详见下文第三节）。仓库中所有主题，如ml4w-modern、ml4w-glass、ml4w-transparent等，都遵循同样的目录结构与config.sh约定，这也正是你能"照葫芦画瓢"复制自定义主题的前提。

二、四步创建自定义主题：官方推荐的标准流程

原文档给出了创建自定义主题的核心操作步骤，完整流程如下：

1. 复制模板文件夹：复制~/.config/waybar/themes/starter目录，并重命名为你自定义的文件夹名（例如mytheme）：

cp -r ~/.config/waybar/themes/starter ~/.config/waybar/themes/mytheme

2. 定义主题名称：打开新目录下的config.sh，将theme_name改为你的主题名（如theme_name="My Theme"），这个名字将出现在主题切换器的选择列表中。

3. 通过切换器选中新主题：按下SUPER+CTRL+T唤起 Waybar Themeswitcher，在列表中选中刚创建的主题，切换器会自动重载 Waybar 并应用新主题。

4. 开始个性化定制：编辑新目录下的config（调整模块）与style.css（调整外观），随时可再次通过切换器回到该主题查看效果。

原文档特别强调两点约定，请务必遵守：

• 模块启停：你可以在config文件中启用、禁用和重新排序 Waybar 模块（详见第四节）；
• 更新保护：你的自定义主题不会被 dotfiles 的后续更新覆盖——这是模板设计的重要承诺，其底层机制我们会在第五节结合launch.sh源码解释。

说明：starter 模板本身位于仓库的 dotfiles/.config/waybar/themes/starter 目录下，与ml4w-minimal等预置主题同级的布局完全一致，README 中"Copy the folder"对应的正是这一结构。

三、主题切换器 Themeswitcher：SUPER+CTRL+T背后发生了什么

新主题建好后，如何在多个主题之间切换？答案是 ML4W 内置的 themeswitcher.sh。该脚本由 Hyprland 按键绑定触发——在 default.lua 中可以看到：

hl.bind(mainMod .. " + CTRL + T", hl.dsp.exec_cmd("~/.config/waybar/themeswitcher.sh"), { description = "Open waybar theme switcher" })

从源码看，它的工作流程分四步：

1. 扫描主题目录：用find $themes_path -maxdepth 2 -type d遍历~/.config/waybar/themes下所有主题文件夹，跳过assets与根目录本身。
2. 读取主题名：对每个主题目录，若存在config.sh则source它，把theme_name追加进选择列表；若不存在则退回用目录路径作为显示名。
3. 弹出选择器：根据~/.config/ml4w/settings/launcher中记录的启动器类型，选择 Walker（-d -i -N）或 Rofi（-dmenu）展示主题列表。
4. 写入并重载：将选中的主题信息以;/主题路径的格式写入~/.config/ml4w/settings/waybar-theme.sh，随后调用~/.config/waybar/launch.sh完成 Waybar 重启与主题应用。

这意味着：任何放在themes/下、含config.sh的目录都会自动出现在切换器中——不需要改任何脚本，复制模板并定义名称即可接入这套机制。这正是原文档"Open config.sh and enter the name of your new theme"步骤的根本原因。

四、模块布局与启停：读懂config的 JSON 结构

原文档指出"你可以在 config 文件中启用、禁用和重新排序 waybar 模块"。以 ml4w-minimal/config 为例，其整体 JSON 结构分为两大部分：

1. 全局设置：图层与间距

{ "layer": "top", "margin-bottom": 0, "margin-left": 0, "margin-right": 0, "spacing": 0, "include": [ "~/.config/ml4w/settings/waybar-quicklinks.json", "~/.config/waybar/modules.json" ] }

layer: "top"让状态栏吸附屏幕顶部；include机制则引入了两组共享定义——ML4W 的快捷链接设置（waybar-quicklinks.json）以及集中托管所有模块通用参数的 modules.json（其中定义了hyprland/workspaces、wlr/taskbar、network、battery等模块的滚动、点击、图标与格式行为，总计 433 行）。这种"公共参数抽离 + 主题局部覆盖"的设计，让每个主题的config保持精简。

2. 模块分组：左、中、右三区

"modules-left": [ "custom/appmenuicon", "hyprland/workspaces", "custom/empty" ], "modules-center": [ "hyprland/window", "custom/empty" ], "modules-right": [ "custom/updates", "pulseaudio", "bluetooth", "network", "battery", "power-profiles-daemon", "group/hardware", "group/tools", "custom/exit", "clock", "tray", "custom/notification", "custom/ml4w-welcome" ]

启停与重排的操作规则非常简单：

• 启用/禁用模块：在对应数组中添加或移除模块名；被注释掉的模块（如示例中的"group/quicklinks"和"backlight"）不会显示；
• 重新排序：直接调整数组内模块的先后顺序即可，数组顺序就是状态栏显示顺序；
• 模块参数：数组外的同名键（如"pulseaudio"、"custom/updates"）用于定义该模块的格式与交互行为，例如更新计数模块：

"custom/updates": { "format": " {}", "escape": true, "return-type": "json", "exec": "~/.config/ml4w/scripts/ml4w-check-system-updates", "restart-interval": 60, "on-click": "~/.config/ml4w/settings/installupdates.sh", "on-click-right": "~/.config/ml4w/settings/software.sh" }

该模块每 60 秒执行一次系统更新检查脚本，左键点击触发更新安装、右键点击打开软件管理，是 ML4W 主题里"数据驱动状态栏"的典型代表。

五、launch.sh：模块开关与"更新不覆盖"的底层保障

新主题为何不会被更新覆盖？答案藏在 launch.sh 中。这个启动脚本在应用主题时做了两件关键的事：

1. 按 ML4W 设置动态启停模块：脚本内置_toggle_module函数，读取~/.config/ml4w/settings/下各开关文件（waybar_appmenu.sh、waybar_quicklinks.sh、waybar_window.sh、waybar_network.sh、waybar_systray.sh等）的值，通过sed在主题config中批量注释/取消注释对应模块：

_toggle_module() { local module_name=$1 local settings_file=$2 local value=$(cat "$settings_file") ... if [ "$value" == "True" ]; then sed -i "s| //\"$module_name\"| \"$module_name\"|g" "$file" else sed -i "s| \"$module_name\"| //\"$module_name\"|g" "$file" fi }

这正是原文档"可以启用、禁用 waybar 模块"声明在 ML4W 体系内的完整实现：模块不仅能在config里手工开关，还能由 GUI 设置中心统一管理。

2. 自定义文件优先加载：启动前，脚本检查主题目录下是否存在config-custom与style-custom.css：

if [ -f ~/.config/waybar/themes${arrThemes[0]}/config-custom ]; then config_file="config-custom" fi if [ -f ~/.config/waybar/themes${arrThemes[1]}/style-custom.css ]; then style_file="style-custom.css" fi

也就是说，ML4W 官方升级只会更新标准config与style.css，而你放在config-custom/style-custom.css里的个性化配置会优先生效。对于按 README 流程整体复制出来的自定义主题文件夹而言，它本就是独立于更新清单之外的目录，自然也不会被覆盖。结论：无论采用哪种方式（整目录复制或config-custom覆盖），自定义成果都能在 dotfiles 更新后完整保留。

六、样式定制要点：以ml4w-minimal的 style.css 为参照

外观层面的定制集中在style.css。ML4W 主题采用 CSS 变量集中管理配色，在 ml4w-minimal/style.css 文件头部可以看到一整套可调色板：

@define-color backgroundlight #FFFFFF; @define-color backgrounddark #FFFFFF; @define-color workspacesbackground1 #FFFFFF; @define-color workspacesbackground2 #CCCCCC; @define-color bordercolor #FFFFFF; @define-color textcolor1 #000000; @define-color textcolor2 #000000; @define-color textcolor3 #FFFFFF; @define-color iconcolor #FFFFFF;

改主题色时只需调整这些顶层变量，所有模块会自动跟随。除此之外，该文件还展示了几个可复用的定制手法：

• 全局字体与圆角：* { font-family: "Fira Sans Semibold", "Font Awesome 7 Free", ...; border-radius: 0px; }，图标字体依次回退到 Font Awesome 与 Material Icons；
• 工作区（Workspaces）动效：#workspaces button设置transition: all 0.5s ease-in-out，hover 时背景圆角变为15px，active工作区用@workspacesbackground2高亮；
• 状态化着色：更新模块按green/yellow/red三个 class 切换颜色（红色#dc2f2f），电池模块在critical且未充电时启用 0.5s 无限闪烁动画blink；
• 图标化自定义模块：#custom-ml4w-welcome、#custom-chatgpt等模块通过background-image: url("../../assets/ml4w-icon.svg")把文字按钮变成图标按钮，#custom-notification直接指定font-family: "Material Icons"使用图标字体；
• 托盘交互反馈：#tray > .needs-attention用-gtk-icon-effect: highlight加红色背景提示"需要关注"的应用。

对照 modules.json 中定义的模块 ID，就能在 CSS 里精准命中每一个模块选择器——这也是官方文档"Start your customization"所指向的完整定制空间。

七、小结与注意事项

围绕 ML4W 的 Waybar 主题体系，本指南给出的完整链路是：复制 starter 模板 → 命名config.sh→ 用SUPER+CTRL+T切换激活 → 在config中编排模块 → 在style.css中调整外观，全程不需要修改任何脚本。整套机制的可靠运行依赖几个前提，使用前请确认：

• 本仓库的 dotfiles 面向 Arch Linux、Fedora 与 openSUSE 发行版部署，themeswitcher.sh还依赖~/.config/ml4w/settings/launcher中配置的 Walker 或 Rofi 作为选择器；
• 主题切换与重载由 themeswitcher.sh 与 launch.sh 协同完成，若手动删除~/.config/ml4w/settings/waybar-theme.sh，launch.sh会自动回退到默认主题；
• 若要彻底关闭 Waybar，创建~/.config/ml4w/settings/waybar-disabled文件即可，launch.sh检测到该文件后会跳过启动。

从仓库的 default.lua 按键绑定，到themeswitcher.sh的目录扫描，再到launch.sh的模块开关与自定义覆盖，ML4W 把"自定义 Waybar 主题"做成了一个开箱即用、且不怕升级覆盖的完整方案——你现在就可以按第二节的四步流程，创建属于自己的第一个主题。

• 桌面应用