如何理解 HyprMod 状态模型:live/saved/default 三值追踪管理未保存更改完全指南
如何理解 HyprMod 状态模型:live/saved/default 三值追踪管理未保存更改完全指南
HyprMod 是一款为 Hyprland 打造的 GTK4/libadwaita 原生设置应用——任何选项修改都会立即生效,满意后再保存。支撑这一体验的核心,正是它底层的状态模型:为每个配置项追踪 live(实时值)、saved(已保存值)、default(默认值)三个值,共同决定"未保存更改"横幅、侧边栏计数徽章,以及保存时真正写入磁盘的内容。
💡 上图正是状态模型的直观体现:右上角的 3 是待保存更改计数徽章,底部横幅写着 "Unsaved changes — applied live, not saved to disk"(已实时生效,但未落盘),侧边栏 General / Decoration 行上的数字则是各分组的脏项计数。
1. 为什么需要"三值追踪"?
在 HyprMod 里,"修改"和"保存"是两件事:
- 修改:通过 Hyprland IPC 立即应用到正在运行的合成器(live preview);
- 保存:把当前状态写入 HyprMod 自己管理的
hyprland-gui.conf,不碰你的主配置文件。
要判断"哪些改动还没保存",光有"当前值"和"磁盘值"两个量是不够的——你还得知道哪些键是 HyprMod 在接管(managed)、哪些只是历史上接管过。于是每个配置项都用一个 OptionState 结构来描述,见 hyprmod/core/state.py:
| 字段 | 含义 |
|---|---|
live_value |
当前实际生效的值(IPC 实时值) |
saved_value |
上次保存时的值(基线) |
default_value |
Hyprland 出厂默认值 |
managed / saved_managed |
当前 / 上次保存时是否处于"接管"状态 |
available |
该键在 IPC 上是否可用 |
2. 脏判定规则:什么算"未保存更改"?
核心判断只有一行,即 is_dirty 属性(state.py):
@property
def is_dirty(self) -> bool:
return self.live_value != self.saved_value or self.managed != self.saved_managed
注意这里有两条轴:
- 值轴:
live_value与saved_value不同 → 脏; - 接管轴:
managed与saved_managed不同 → 也脏。
第二条轴很微妙:你把某个选项改回"已保存值"时,HyprMod 会认为你不再需要接管它,managed 随之变为 False——这本身就是一次未保存的变化(保存后配置文件里将不再出现这条覆盖)。保存成功时,mark_saved() 会把两条轴一次性对齐(state.py):
def mark_saved(self):
for s in self.options.values():
s.saved_value = s.live_value
s.saved_managed = s.managed
3. 基线为什么取自 live 值而不是磁盘?
这是一个容易踩坑的细节。注册选项时(register()),saved_value 的初始基线来自 IPC 实时值,而不是磁盘内容。原因是:
- 如果你之前手动执行过
hyprctl setctl ...之类的命令,磁盘文件和实际生效值就不一致; - 以磁盘值为基线的话,每次启动都会误报"有未保存更改";
- 以 live 值为基线,
is_dirty追踪的语义就变成了"本次会话中用户改了什么",干净且符合直觉。
官方测试对这一不变量有专门覆盖,见 tests/test_state.py 的模块注释。
4. 未保存更改如何驱动整个 UI?
AppState.has_dirty()(state.py)只要任一选项脏就返回 True;窗口层再叠加各分区页的脏状态,见 window.py。一个状态变化会联动四处 UI:
- 顶部横幅:
DirtyBanner上滑显示 "Unsaved changes",带 Discard / Save now 按钮(ui/banner.py);保存后切换为 "Changes saved to disk" 并自动隐藏(show_saved())。 - 顶栏计数芯片:任何页面顶栏的
PendingChip显示未保存条数,点击直达 Pending Changes 页(ui/pending_chip.py)。 - 侧边栏徽章:按 schema 分组统计脏选项数,显示在对应行上(_update_sidebar_badges())。
- Pending Changes 页:聚合所有来源的 PendingChange 条目,分为 Modified / Added / Removed 三类,并附带一次真实的配置 diff 预览——对比"已保存文件"与"下次保存将要写入的内容"(pages/pending.py)。
自动保存模式下横幅会被刻意隐藏:此时"脏"只是 800ms 防抖窗口内的瞬态,显示出来只会闪烁(见 window.py 的防抖调度与 _update_banner() 的 gating 逻辑)。
5. 撤销与丢弃:三值如何回滚
- 单项丢弃:
discard_one()把live_value拉回saved_value,同时通过 IPC 让合成器回到该值(state.py); - 全部丢弃:
discard_dirty()委托 IPC 层做真正的回滚,再把结果镜像回每个OptionState(state.py); - Ctrl+Z 撤销栈:
UndoManager用线性栈管理每类变更的快照条目,同键连续修改会自动合并成一条(core/undo.py); - 配置重载保脏:
reload_preserving_dirty()在 Hyprland 重载后重新应用所有未保存值,避免重载把内存态冲掉(state.py)。
6. 保存的完整闭环
点击 "Save now" 后,窗口执行 _perform_save():
config.write_all(...)将get_all_live_values()(所有被接管的 live 值)与各区段内容写入hyprland-gui.conf;app_state.mark_saved()+ 各分区页mark_saved()清除脏标志;- 清空撤销栈、刷新所有"已修改"指示器、重建 Pending Changes 页;
- 若规则类分区有变化,还会触发一次 Hyprland 重载,因为规则没有可增删的 IPC。
像动画曲线这类"分区页"不直接走 AppState,而是由各自的 SectionPage 基类维护同构的 is_dirty / mark_saved / discard 生命周期(pages/section.py),最终汇入同一套横幅、徽章与 Pending Changes 聚合流程——这正是三值模型作为"单一事实来源"的价值:无论改动来自哪个页面,未保存状态的语义都完全一致。
7. 小结
| 概念 | 一句话 |
|---|---|
live_value |
此刻实际生效的值 |
saved_value |
上次保存的基线(本次会话起点) |
default_value |
Hyprland 出厂默认值 |
is_dirty |
值或接管状态任一与已保存不同 |
mark_saved() |
保存后把基线对齐到 live,消除脏状态 |
三值追踪 + 双轴脏判定,让 HyprMod 能精确回答"你这次会话改了什么、哪些还没落盘",并把答案实时投射到横幅、徽章、撤销栈与 diff 预览中。想深入源码,建议从 hyprmod/core/state.py 开始,再顺着 hyprmod/window.py 的保存流程走一遍。

