Wayle 是一款基于 Rust + GTK4 + Relm4 的 Wayland 桌面 Shell，自带状态栏、通知、OSD 和主题系统。本文将揭秘 Wayle 状态栏（Bar）的底层架构：它是如何用 Relm4 的FactoryComponent配合工厂模式，把配置文件里的一行left = ["dashboard"]动态变成屏幕上的按钮的。无论你是想定制状态栏，还是对 GUI 架构设计感兴趣，这篇指南都会带你读懂其中的设计哲学。

Wayle 状态栏与桌面预览

一、先看结果：一个声明式配置的状态栏

在 Wayle 中，状态栏长什么样由config.toml声明，例如：

[[bar.layout]] monitor = "*" left = ["dashboard"] center = ["clock"] right = ["battery", "network", "volume", "systray"]

每个条目（BarItem）有三种形态，可自由混排：

• 普通模块："clock"
• 带 CSS 类的模块：{ module = "clock", class = "primary" }，用于逐实例定制样式
• 命名分组：{ name = "status", modules = ["battery", "volume"] }，分组会渲染成共享容器，名字直接成为 CSS ID 选择器

这些类型定义在 types/mod.rs 的BarLayout、BarItem、ModuleRef与BarModule中，完整字段参考官方文档 docs/config/bar.md。

配置改动会热重载，无需重启 Shell——这背后的机制正是本文的主角。

二、状态栏的骨架：Bar 与三条 FactoryVecDeque

每个显示器对应一个Bar组件（mod.rs），它通过 layer-shell 协议锚定到屏幕边缘，内部是一个gtk::CenterBox：

关键在于：区段里装的不是一个个具体的模块控件，而是BarItemFactory工厂实例组成的动态队列。FactoryVecDeque是 Relm4 提供的容器，能按"插入 / 移动 / 删除"语义批量管理子工厂，每个工厂再自行决定往父gtk::Box里塞什么。

三、FactoryComponent：一个工厂，多种模块

打开 factory.rs，整个BarItemFactory不到 130 行：

#[relm4::factory(pub(crate))] impl FactoryComponent for BarItemFactory { type Init = BarItemFactoryInit; type ParentWidget = gtk::Box; view! { #[root] gtk::Box { add_css_class: "bar-item" } } }

它的init_model逻辑非常直白：

1. 拿到配置项BarItem（单个模块或一组模块）；
2. 调用create_module()逐个生成ModuleInstance；
3. 在init_widgets中把这些模块的 widget 追加进根Box，并根据bar.location自动切换水平 / 垂直方向；
4. 对分组项加上bar-group类和 CSS ID（即group.name），让#status这类选择器可以直接命中分组容器。

还有一个容易被忽略的细节——sync_container_visibility：它监听子控件的visible变化，当某个模块因缺少系统服务而隐藏时，父容器会自动收缩，不会出现空洞的间距。这就是为什么在没有蓝牙主机的机器上，状态栏依然紧凑。

四、模块注册表：28 个模块如何被统一调度

每个具体模块（clock、battery、volume……）都位于 modules/ 目录下的独立子目录，且都实现了同一个工厂接口（定义在 registry.rs）：

pub(crate) trait ModuleFactory { fn create(...) -> Option<ModuleInstance>; }

以时钟模块为例，clock/factory.rs 的Factory::create只做一件事：组装ClockInit，启动ClockModule组件，用dynamic_controller把具体类型擦除成Box<dyn ModuleController>返回。

所有模块的映射则由 modules/mod.rs 中的register_modules!宏一次性声明：

register_modules! { Battery => battery::Factory, Clock => clock::Factory, Volume => volume::Factory, // ……共 28 个内置模块 }

这套设计的哲学是"注册表 + 工厂 + 类型擦除"：

• 新增模块零侵入：只需新增子目录、写一个Factory、在宏里加一行，Bar和FactoryVecDeque完全不感知；
• 优雅降级：工厂返回Option。依赖缺失（如没有 Power 守护进程、非 Hyprland 环境）时返回None并写一条warn!日志，由 registry.rs 的require_service/require_hyprland等助手统一处理，状态栏不会崩溃；
• 共享下拉面板：所有模块通过Rc<DropdownRegistry>（dropdowns/registry.rs）访问同一份下拉面板注册表，音频面板只构建一次，被 volume、media 等多个模块复用。

五、热重载的精髓：两阶段布局 Diff

配置监听在 watchers/layout.rs：它订阅bar.layout的配置流与 IPC 的隐藏指令，变化时先把extends继承链展开、按显示器匹配（精确匹配优先，其次"*"通配），再发送BarCmd::LayoutLoaded。

真正的渲染在 methods.rs 的apply_layout→rebuild_section，它执行一个两阶段 Diff：

1. Remove（删除）：遍历旧列表，新列表中不存在的条目从队列中移除；用一个不断缩小的新列表副本来正确处理重复模块；
2. Place（归位）：按位置遍历新列表——位置已正确则跳过；模块存在但位置不对则move_to（只移动 widget，不重建）；完全新增才走FactoryVecDeque::insert真正创建工厂。

源码注释里说得很明白："Modules that stay in the config are left alone (not destroyed and recreated), so they keep their widgets and state."（配置中保留的模块原样不动，保留 widget 和状态。）

这是典型的最小变更原则：拖动音量模块从左到右，它的时间显示、展开的下拉面板、未读计数都不会丢失。配合matches()（factory.rs 中通过比较BarItem实现），整个状态栏可以做到毫秒级、无闪烁的布局更新。

六、设计哲学小结

一句话总结 Wayle 状态栏的设计哲学：配置即数据，工厂即边界，Diff 即动画。声明式配置负责"要什么"，FactoryComponent负责"怎么造"，两阶段 Diff 负责"如何平滑地变"。这也是 Relm4 在长生命周期 GUI 场景中比"全量重建"更胜一筹的范例。

延伸阅读

• 状态栏配置参考：docs/config/bar.md
• 模块配置文档：docs/config/modules/
• 布局指南：docs/guide/bars-and-layouts.md
• 设置界面源码：crates/wayle-settings/src/pages/bar/
• 自定义模块指南：docs/guide/custom-modules.md