YaLTeR/niri 项目键位绑定配置详解

YaLTeR/niri 项目键位绑定配置详解

niri A scrollable-tiling Wayland compositor. 项目地址: https://gitcode.com/gh_mirrors/ni/niri

键位绑定基础概念

在 YaLTeR/niri 项目中，键位绑定是用户与窗口管理器交互的核心方式之一。通过精心配置的键位绑定，用户可以高效地控制系统行为、启动应用程序以及执行各种窗口管理操作。

键位绑定配置位于配置文件的 binds {} 部分，这是一个需要用户显式声明的重要部分，系统不会自动填充默认值。每个绑定由一个热键和一个动作组成，基本语法如下：

binds {
    修饰键+按键 { 动作; }
}

修饰键详解

YaLTeR/niri 支持多种修饰键组合，这些修饰键可以灵活组合使用：

• Ctrl 或 Control：控制键
• Shift：上档键
• Alt：替代键
• Super 或 Win：Windows/Command 键
• ISO_Level3_Shift 或 Mod5：AltGr 键（某些键盘布局上）
• ISO_Level5_Shift：可用于 xkb lv5 选项
• Mod：特殊修饰键

其中 Mod 是一个智能修饰键，会根据运行环境自动切换：

• 在 TTY 下运行时等同于 Super
• 在嵌套窗口(winit)中运行时等同于 Alt

这种设计使得用户可以在测试环境中使用 niri 而不会与宿主系统的快捷键冲突。

键位识别技巧

要确定特定按键的 XKB 名称，可以使用专门的按键检测工具。当按下按键时，工具会输出类似以下信息：

sym: Left (65361)

这里的 Left 就是按键的 XKB 名称。需要注意的是，对于需要 Shift 组合的按键，必须明确写出 Shift 修饰键和基础键名。

高级绑定特性

重复触发控制

从 0.1.8 版本开始，键位绑定默认支持重复触发（按住不放会连续触发）。可以通过 repeat=false 禁用此功能：

Mod+T repeat=false { spawn "alacritty"; }

冷却时间设置

可以为绑定设置冷却时间，防止过快重复触发：

Mod+T cooldown-ms=500 { spawn "alacritty"; }

这个特性特别适用于滚动绑定。

滚动绑定配置

YaLTeR/niri 支持鼠标滚轮和触摸板滚动的绑定，这些绑定会根据 natural-scroll 设置自动调整方向。

鼠标滚轮绑定

Mod+WheelScrollDown cooldown-ms=150 { focus-workspace-down; }

触摸板滚动绑定

触摸板滚动是连续的，系统会将其分割为离散的触发间隔：

Mod+TouchpadScrollDown { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02+"; }

鼠标点击绑定

从 25.01 版本开始支持鼠标点击绑定：

Mod+MouseLeft { close-window; }

注意：绑定 Mod+MouseLeft 或 Mod+MouseRight 会覆盖对应的窗口移动/调整大小手势。

热键覆盖标题定制

从 25.02 版本开始，可以自定义热键覆盖对话框中显示的标题：

Mod+Shift+S hotkey-overlay-title="Toggle Dark/Light Style" { spawn "some-script.sh"; }

也可以隐藏默认绑定：

Mod+Q hotkey-overlay-title=null { close-window; }

标题支持 Pango 标记语言，可以实现丰富的文本样式。

常用动作详解

程序启动(spawn)

启动应用程序的基本语法：

Mod+T { spawn "alacritty"; }

特殊注意事项：

• 参数需要明确分隔
• 不支持直接的环境变量扩展和 ~ 扩展
• 可以通过 shell 手动实现复杂命令

退出系统(quit)

退出 niri 并显示确认对话框：

Mod+Shift+E { quit; }

跳过确认对话框：

Mod+Shift+E { quit skip-confirmation=true; }

屏幕过渡效果

从 0.1.6 版本开始支持屏幕过渡效果：

Mod+Return { do-screen-transition; }

可以设置延迟时间：

Mod+Return { do-screen-transition delay-ms=100; }

窗口透明度切换

从 25.02 版本开始支持窗口透明度规则切换：

Mod+O { toggle-window-rule-opacity; }

屏幕截图功能

提供三种截图方式：

• screenshot：交互式截图界面
• screenshot-screen：截取当前屏幕
• screenshot-window：截取当前窗口

可以控制是否保存到磁盘：

Ctrl+Print { screenshot-screen write-to-disk=false; }

从 25.05 版本开始可以隐藏鼠标指针：

Print { screenshot show-pointer=false; }

键盘快捷键抑制切换

从 25.02 版本开始支持快捷键抑制切换，防止应用程序锁定系统：

Mod+Escape { toggle-keyboard-shortcuts-inhibit; }

可以设置特定绑定始终有效：

Super+Alt+L allow-inhibiting=false { spawn "swaylock"; }

通过以上配置，用户可以打造出既高效又符合个人习惯的操作环境，充分发挥 YaLTeR/niri 窗口管理器的强大功能。

niri A scrollable-tiling Wayland compositor. 项目地址: https://gitcode.com/gh_mirrors/ni/niri