如何理解 HyprMod 状态模型:live/saved/default 三值追踪管理未保存更改完全指南

原创2026-10-14 23:42:361,380 阅读

如何理解 HyprMod 状态模型:live/saved/default 三值追踪管理未保存更改完全指南

HyprMod 是一款为 Hyprland 打造的 GTK4/libadwaita 原生设置应用——任何选项修改都会立即生效,满意后再保存。支撑这一体验的核心,正是它底层的状态模型:为每个配置项追踪 live(实时值)、saved(已保存值)、default(默认值)三个值,共同决定"未保存更改"横幅、侧边栏计数徽章,以及保存时真正写入磁盘的内容。

HyprMod 显示器配置页展示未保存更改横幅与待保存计数徽章

💡 上图正是状态模型的直观体现:右上角的 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

注意这里有两条轴:

  1. 值轴:live_value 与 saved_value 不同 → 脏;
  2. 接管轴: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:

  1. 顶部横幅:DirtyBanner 上滑显示 "Unsaved changes",带 Discard / Save now 按钮(ui/banner.py);保存后切换为 "Changes saved to disk" 并自动隐藏(show_saved())。
  2. 顶栏计数芯片:任何页面顶栏的 PendingChip 显示未保存条数,点击直达 Pending Changes 页(ui/pending_chip.py)。
  3. 侧边栏徽章:按 schema 分组统计脏选项数,显示在对应行上(_update_sidebar_badges())。
  4. 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():

  1. config.write_all(...) 将 get_all_live_values()(所有被接管的 live 值)与各区段内容写入 hyprland-gui.conf;
  2. app_state.mark_saved() + 各分区页 mark_saved() 清除脏标志;
  3. 清空撤销栈、刷新所有"已修改"指示器、重建 Pending Changes 页;
  4. 若规则类分区有变化,还会触发一次 Hyprland 重载,因为规则没有可增删的 IPC。

HyprMod 贝塞尔曲线编辑器与实时动画预览

像动画曲线这类"分区页"不直接走 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 的保存流程走一遍。

登录后查看全文
hyprmod