komorebi 浮动窗口管理:toggle-float 与 toggle-float-override 命令深度解析

原创2026-09-21 14:31:221,692 阅读
文章标签:桌面应用CLI

komorebi 浮动窗口管理:toggle-float 与 toggle-float-override 命令深度解析

导读

本文围绕 komorebi 平铺窗口管理器的浮动窗口机制展开,重点解析两条核心 CLI 命令:用于将当前聚焦窗口在"平铺/浮动"两种形态间切换的 toggle-float,以及用于让所有新窗口默认以浮动模式打开的 toggle-float-override。通过阅读本文,你将掌握这两条命令的完整用法、底层调用链与窗口归属处理逻辑,并能结合 Placement 配置、工作区级覆盖与 whkdrc/AHK 快捷键绑定,构建一套灵活可控的浮动窗口工作流。

toggle-float:切换聚焦窗口的浮动模式

关联文档 toggle-float.md 给出的命令定义非常简洁:

Toggle floating mode for the focused window

Usage: komorebic.exe toggle-float

Options:
  -h, --help
          Print help

该命令作用于当前聚焦窗口:如果窗口当前处于平铺(tiling)状态,执行后转为浮动(floating)状态;如果已经浮动,则执行后恢复为平铺状态。命令本身不接受任何额外参数,仅支持 -h/--help 查看帮助。

命令分发链路

在 komorebic 客户端侧,toggle-float 子命令被转换为 SocketMessage::ToggleFloat 消息发送给 komorebi 守护进程(见 komorebic/src/main.rs 中的 SubCommand::ToggleFloat 分支)。

在守护进程侧,消息在 process_command.rs 中被分发:

SocketMessage::ToggleFloat => self.toggle_float(false)?,

注意这里传入的参数是 false,即 force_float = false,表示执行真正的"切换"语义(浮动则取消浮动,平铺则转为浮动),而不是强制浮动。在 window_manager.rs 中可以看到,其他场景(如 session 浮动规则命中时)会以 self.toggle_float(true) 的方式调用,表示强制把窗口置为浮动,不做"切回平铺"的处理。

toggle_float 的核心逻辑

toggle_float 的实现位于 window_manager.rs:

pub fn toggle_float(&mut self, force_float: bool) -> eyre::Result<()> {
    let hwnd = WindowsApi::foreground_window()?;
    let workspace = self.focused_workspace_mut()?;
    if workspace.monocle_container.is_some() {
        tracing::warn!("ignoring toggle-float command while workspace has a monocle container");
        return Ok(());
    }
    ...
}

其处理流程可归纳为以下四步:

  1. 获取前台窗口:通过 WindowsApi::foreground_window() 取得当前前台窗口的 HWND,因此命令始终作用于"当前聚焦窗口"。
  2. monocle 保护:若当前工作区存在 monocle 容器(单窗口聚焦模式),命令会被直接忽略并输出警告日志,避免在 monocle 模式下破坏窗口归属。
  3. 状态判定:遍历当前工作区的浮动窗口列表,判断目标窗口是否已是浮动窗口。
  4. 形态切换:
    • 若窗口已在浮动列表且 force_float 为 false:将工作区层(WorkspaceLayer)置为 Tiling,并调用 unfloat_window() 把窗口重新纳入平铺容器。
    • 否则:将工作区层置为 Floating,并调用 float_window() 将窗口从平铺容器中取出、加入浮动列表。

切换完成后调用 update_focused_workspace(is_floating_window, true) 触发重排与渲染。

浮动与解除浮动的窗口归属处理

浮动不是简单地把窗口"扔到一边",而是涉及窗口在容器中的迁入迁出:

  • float_window(window_manager.rs):先取得聚焦显示器的工作区(work area),再调用 workspace.new_floating_window()。该函数在 workspace.rs 中处理了几种来源:若存在最大化窗口则取出该窗口;若存在 monocle 容器则取出其中的聚焦窗口;否则从当前聚焦容器中移除聚焦窗口。窗口进入浮动列表后,会根据 toggle_float_placement 决定是否居中/调整尺寸,最后聚焦到该窗口。
  • unfloat_window:调用 workspace.new_container_for_floating_window()(workspace.rs),将当前聚焦的浮动窗口从浮动列表移除,创建新的默认容器并插入到原聚焦容器索引位置,使窗口重新回归平铺布局。

这也解释了为什么反复执行 toggle-float 时,窗口能在两种形态间稳定往返:浮动时保留窗口对象本身,解除浮动时窗口回到容器体系并立即参与下一次平铺重排。

与最大化/单窗口模式的联动

从 new_floating_window 的实现可以看出,窗口的浮动与最大化、monocle 状态存在联动:浮动操作会先尝试取出最大化窗口或 monocle 容器中的窗口。反过来,toggle_float 又在入口处显式拒绝了存在 monocle 容器的工作区。因此在实际使用中,建议在普通平铺工作区中使用该命令,若已进入 monocle 或最大化状态,应先退出相应模式再切换浮动。

toggle-float-override:让所有新窗口默认浮动

关联文档 toggle-float-override.md 给出的定义:

Enable or disable float override, which makes it so every new window opens in floating mode

Usage: komorebic.exe toggle-float-override

Options:
  -h, --help
          Print help

toggle-float-override 是一个全局开关,启用后所有新打开的窗口都会以浮动模式启动,而不是被纳入平铺布局。与 toggle-float(只影响当前聚焦窗口)不同,它改变的是"后续新窗口的默认行为"。

底层实现

该命令在 process_command.rs 中直接翻转全局配置标志:

SocketMessage::ToggleFloatOverride => {
    self.window_management_behaviour.float_override =
        !self.window_management_behaviour.float_override;
}

即每次执行都会将 WindowManagementBehaviour.float_override 布尔值取反,实现"启用 ↔ 禁用"的切换语义。该标志没有"查询当前状态"的配套命令,若需确认状态,可通过订阅状态输出(见 subscribe-socket.md 等文档)观察窗口行为变化。

新窗口的处理分支

新窗口的归属判定在 process_event.rs 中完成。当窗口事件到来时,会依次判定浮动应用规则(floating_applications)、float override 与 floating layer 行为,最终进入浮动或平铺分支:

if behaviour.float_override
    || behaviour.floating_layer_override
    || (should_float && !matches!(event, WindowManagerEvent::Manage(_)))
{
    let placement = if behaviour.floating_layer_override {
        behaviour.floating_layer_placement
    } else if behaviour.float_override {
        behaviour.float_override_placement
    } else {
        behaviour.float_rule_placement
    };
    workspace.floating_windows_mut().push_back(window);
    workspace.layer = WorkspaceLayer::Floating;
    ...
}

可以看到 float_override 一旦为 true,新窗口无条件进入浮动列表,且定位方式由 float_override_placement 决定(见下文 Placement 一节)。反之,新窗口按 WindowContainerBehaviour::Create / Append 语义进入平铺容器。

工作区级覆盖优先级

在 window_manager.rs 中,构建窗口管理行为时存在优先级链:

let float_override = if let Some(float_override) = workspace.float_override {
    float_override
} else {
    self.window_management_behaviour.float_override
};

即工作区(workspace)级 float_override 优先于全局设置。这意味着一方面可以用 toggle-float-override 控制全局默认行为;另一方面,如果某个工作区通过 toggle-workspace-float-override(见 toggle-workspace-float-override.md)单独设置了覆盖,则该工作区不受全局开关影响。这一点在混用多显示器、多工作区场景下尤为重要。

Placement:浮动窗口的定位策略

无论是 toggle-float 后的窗口、float override 生成的新窗口,还是浮动规则匹配的窗口,其位置与尺寸行为都由 Placement 枚举控制。该枚举定义在 core/mod.rs:

pub enum Placement {
    /// Does not change the size or position of the window
    None,
    /// Center the window without changing the size
    Center,
    /// Center the window and resize it according to the `AspectRatio`
    CenterAndResize,
}

三个取值的含义与默认场景:

取值 行为 说明
None 不改变窗口尺寸与位置 浮动窗口保留其原始几何信息
Center 居中但不改尺寸 窗口在工作区内居中
CenterAndResize 居中并按宽高比调整尺寸 按 AspectRatio 约束进行缩放,保证比例

在 core/mod.rs 中,Placement 提供了 should_center() 与 should_resize() 两个辅助方法:Center 与 CenterAndResize 都返回居中为真,仅 CenterAndResize 返回调整尺寸为真。float_window 正是依据这两个方法决定是否调用 window.center(&work_area, should_resize())。

各场景默认值

不同场景下 Placement 的默认值并不相同,均定义在 static_config.rs 的 WindowManagementBehaviour 中:

配置字段 作用 默认值
toggle_float_placement 手动 toggle-float 后窗口的定位 CenterAndResize
floating_layer_placement 浮动层行为为 Float 时新窗口的定位 Center
float_override_placement float override 生效时新窗口的定位 None
float_rule_placement 命中 floating_applications 规则时新窗口的定位 None

这一点很值得注意:手动切换浮动(toggle-float)默认会把窗口居中并按比例调整大小,而 float override 生成的新窗口默认保留原始位置尺寸。如果你希望通过 override 打开的窗口也居中显示,就需要显式配置 float_override_placement。

配置文件中的浮动行为设置

浮动相关配置位于 window_management_behaviour 配置块下,完整的 JSON Schema 定义可参考仓库根目录的 schema.json:

{
  "window_management_behaviour": {
    "float_override": false,
    "floating_layer_behaviour": "Tile",
    "toggle_float_placement": "CenterAndResize",
    "floating_layer_placement": "Center",
    "float_override_placement": "None",
    "float_rule_placement": "None"
  }
}

各字段说明(与 static_config.rs 中字段级注释及 schema.json 一致):

  • float_override:布尔值,默认 false,等价于命令 toggle-float-override 的持久化配置;
  • floating_layer_behaviour:Tile 或 Float,决定工作区处于浮动层时新窗口如何处理;
  • toggle_float_placement / floating_layer_placement / float_override_placement / float_rule_placement:分别对应上述四种场景的 Placement 取值。

静态配置通过 static_config.rs 的加载逻辑在启动时写入 WindowManagementBehaviour,因此运行时使用命令切换的状态不会写回配置文件,重启 komorebi 后将以配置文件中的值为准。若希望某台机器默认启用 float override,直接修改配置比每次启动后手动执行命令更可靠。

快捷键绑定示例

官方推荐的快捷键配置(见 whkdrc.sample)将 Alt + T 绑定到 toggle-float:

alt + t                 : komorebic toggle-float

AHK 用户可以在 komorebi.ahk.txt 中找到对应绑定:

!t::Komorebic("toggle-float")

同理,可为 toggle-float-override 增加独立快捷键(whkdrc 语法):

alt + f                 : komorebic toggle-float-override

建议将两者绑定在相邻按键上形成"单窗口浮动 + 全局浮动开关"的组合:日常使用 toggle-float 处理个别需要浮动的窗口(如计算器、弹窗),在需要临时自由摆放多个窗口时再开启 toggle-float-override,用完再按一次关闭,恢复平铺管理。

与浮动相关的其他命令

在 komorebi 的浮动体系中,toggle-float 与 toggle-float-override 只是入口之一,与之配套的能力包括:

  • toggle-workspace-float-override:工作区级 float override,优先级高于全局开关(见 toggle-workspace-float-override.md);
  • session-float-rule / session-float-rules:为当前前台窗口创建仅本次会话有效的浮动规则,规则命中时窗口强制浮动(process_command.rs 中 SessionFloatRule 分支在写入规则后即调用 toggle_float(true) 强制浮动);
  • floating_applications 配置:通过静态配置声明常驻浮动的应用,命中时新窗口直接进入浮动列表,定位由 float_rule_placement 控制;
  • clear-session-float-rules:清除会话级浮动规则,恢复平铺行为。

典型的组合策略是:用 floating_applications 处理"永远浮动"的应用(如某些必须保持浮动的工具窗),用 session-float-rule 处理"本次登录浮动"的应用,用 toggle-float 处理"临时浮动一次",用 toggle-float-override 处理"接下来所有窗口都浮动"的临时场景。四个层级互不冲突,覆盖从持久到临时的全部浮动需求。

总结

toggle-float 与 toggle-float-override 是 komorebi 浮动窗口管理的两块基石:前者以窗口为粒度,在平铺与浮动之间切换当前聚焦窗口,底层涉及窗口在容器与浮动列表之间的迁移,并由 toggle_float_placement 控制浮动后的定位;后者以全局为粒度,翻转 float_override 标志,使后续所有新窗口默认浮动,定位由 float_override_placement 决定,且可被工作区级设置覆盖。理解这两条命令及其背后的 Placement 语义、配置文件字段与快捷键绑定方式,即可在不脱离平铺布局的前提下,随时为特定窗口或特定时段切换出自由浮动的操作空间。

登录后查看全文
komorebi