wl-kbptr键盘选鼠标:Sway与Hyprland快捷键绑定2合1实战教程
wl-kbptr键盘选鼠标:Sway与Hyprland快捷键绑定2合1实战教程
wl-kbptr 是一款在 Wayland 桌面下用键盘精准控制鼠标指针的工具,本教程面向新手,手把手教你在 Sway 和 Hyprland 两大主流 Wayland 合成器上完成快捷键绑定,实现"手不离键盘就能移动、点击、拖拽鼠标"的完整工作流。
一、wl-kbptr 是什么?为什么值得装
在 Wayland 环境下,鼠标指针不再能被全局随意移动,而 wl-kbptr 通过 wlr-layer-shell 在屏幕上覆盖一层选择界面,让你用键盘快速"跳转 + 点击"鼠标位置,速度远超逐格移动光标。
它提供 5 种可自由组合的模式(详见 README.md):
| 模式 | 作用 | 使用方式 |
|---|---|---|
tile |
屏幕网格选区 | 输入网格上的字母标签 |
bisect |
递归二分选区 | 每次二选一,Enter/Space 跳到红点位置 |
split |
逐级分割选区 | 方向键上下左右分割 |
floating |
任意区域选区 | 标准输入传入,或 OpenCV 自动检测 |
click |
在选区中心触发一次点击 | 作为链尾模式使用 |
模式之间可以链式组合,选错时按 Backspace 随时回退上一步。核心实现位于 src/mode.h 定义的 mode_interface 接口中。
合成器兼容性(摘自 README.md):
- ✅ Sway、Hyprland、niri、dwl、labwc 均已测试通过
- ❗ KWin:部分支持;❌ Mutter:不支持
也就是说,Sway 与 Hyprland 用户开箱即用,这正是本教程的主角。
二、快速安装 wl-kbptr
发行版包管理器安装
如果你的发行版已打包(如 Fedora 可用 dnf in wl-kbptr,Arch 有 AUR 包),直接安装即可,通常已启用 OpenCV 检测功能。
从源码编译(通用方案)
需要 meson、ninja、wayland、cairo、xkbcommon 等依赖(详见 README.md 的 Dependencies 一节):
git clone https://gitcode.com/gh_mirrors/wl/wl-kbptr
cd wl-kbptr
meson setup build --buildtype=release -Dopencv=enabled
meson compile -C build
meson install -C build
💡
-Dopencv=enabled开启floating模式的自动目标检测(可选,见 meson.options)。用wl-kbptr --version检查输出是否包含opencv即可确认。
三、Sway 快捷键绑定实战(Mouse 模式)
一键粘贴的完整绑定配置
将以下配置加入 ~/.config/sway/config,它定义了一个 Mouse 模式,用 g 系键盘布局实现移动、点击、滚动:
mode Mouse {
bindsym a mode default, exec 'wl-kbptr-sway-active-win; swaymsg mode Mouse'
bindsym Shift+a mode default, exec 'wl-kbptr; swaymsg mode Mouse'
# Mouse move
bindsym h seat seat0 cursor move -15 0
bindsym j seat seat0 cursor move 0 15
bindsym k seat seat0 cursor move 0 -15
bindsym l seat seat0 cursor move 15 0
# Left button
bindsym s seat seat0 cursor press button1
bindsym --release s seat seat0 cursor release button1
# Middle button
bindsym d seat seat0 cursor press button2
bindsym --release d seat seat0 cursor release button2
# Right button
bindsym f seat seat0 cursor press button3
bindsym --release f seat seat0 cursor release button3
bindsym Escape mode default
}
bindsym $mod+g exec wl-kbptr-sway-active-win -o modes=floating','click -o mode_floating.source=detect
bindsym $mod+Shift+g mode Mouse
各按键速查表
| 按键 | 功能 |
|---|---|
h / j / k / l |
指针左 / 下 / 上 / 右移动 |
s / d / f |
左键 / 中键 / 右键点击 |
a |
智能跳转到当前活动窗口中心(自动检测模式) |
Shift+a |
全屏网格跳转指针 |
Escape |
退出 Mouse 模式 |
入口快捷键说明
$mod+g:一键智能点击——在当前聚焦窗口内自动检测目标并点击,是效率最高的用法$mod+Shift+g:进入 Mouse 模式,手动操控指针
其中 a 键的"活动窗口"定位由仓库自带的辅助脚本 helpers/wl-kbptr-sway-active-win 完成:它用 swaymsg -t get_tree 取出聚焦窗口的 rect,再传给 wl-kbptr --restrict 限定选区,避免选到窗口外的区域。
四、Hyprland 快捷键绑定实战(cursor 子图)
一键粘贴的完整绑定配置
Hyprland 用 submap(子图) 机制实现同样的效果,加入 ~/.config/hypr/hyprland.conf:
# Cursor submap (similar to the Mouse mode in Sway)
submap=cursor
# Jump cursor to a position
bind=,a,exec,hyprctl dispatch submap reset && wl-kbptr && hyprctl dispatch submap cursor
# Cursor movement
binde=,j,exec,wlrctl pointer move 0 10
binde=,k,exec,wlrctl pointer move 0 -10
binde=,l,exec,wlrctl pointer move 10 0
binde=,h,exec,wlrctl pointer move -10 0
# Left button
bind=,s,exec,wlrctl pointer click left
# Middle button
bind=,d,exec,wlrctl pointer click middle
# Right button
bind=,f,exec,wlrctl pointer click right
# Scroll up and down
binde=,e,exec,wlrctl pointer scroll 10 0
binde=,r,exec,wlrctl pointer scroll -10 0
# Scroll left and right
binde=,t,exec,wlrctl pointer scroll 0 -10
binde=,g,exec,wlrctl pointer scroll 0 10
# Exit cursor submap
bind=,escape,exec,hyprctl keyword cursor:inactive_timeout 3; hyprctl keyword cursor:hide_on_key_press true; hyprctl dispatch submap reset
submap = reset
# Entrypoint
bind=$mainMod,g,exec,hyprctl keyword cursor:inactive_timeout 0; hyprctl keyword cursor:hide_on_key_press false; hyprctl dispatch submap cursor
提示:如果你不使用 cursor 超时或
hide_on_key_press功能,可以删掉escape与入口行中对应的hyprctl keyword调用(原注释有说明)。
各按键速查表
| 按键 | 功能 |
|---|---|
$mainMod+g |
进入 cursor 子图 |
a |
全屏跳转指针(wl-kbptr 网格选择) |
h / j / k / l |
指针左 / 下 / 上 / 右移动 |
s / d / f |
左键 / 中键 / 右键点击 |
e / r / t / g |
滚动:下 / 上 / 左 / 右 |
Escape |
退出子图 |
五、进阶:模式链与常用选项
命令行参数定义见 src/main.c 的 print_usage:
| 参数 | 说明 |
|---|---|
-o key=value |
临时覆盖配置项,如 -o modes=tile,bisect |
-r, --restrict=wxh+x+y |
限定在指定区域(wxh+x+y 格式) |
-O, --output |
多显示器时指定使用哪块屏幕 |
-p, --only-print |
仅打印选区,不移动指针(KWin 用户配合 ydotool 使用) |
-d, --drag |
两次选择之间执行"点击-拖拽",适合选中文本、拖动界面元素 |
模式链示例:
# 先网格粗选,再二分精确定位(推荐日常组合)
wl-kbptr -o modes=tile,bisect
# 自动检测目标后直接点击
wl-kbptr -o modes=floating,click -o mode_floating.source=detect
完整配置项(颜色、字体、home_row_keys 点击键位等)参考 config.example,配置默认从 $XDG_CONFIG_HOME/wl-kbptr/config 读取,运行 wl-kbptr --help-config 可查看每一项的详细说明。
六、常见问题排查
- 按了快捷键没反应? 确认你的合成器支持
wlr-virtual-pointer-unstable-v1与wlr-layer-shell-unstable-v1协议,Mutter 等不支持(见 README.md 的兼容性表)。 - 多显示器指针跳错屏幕? 用
-O指定输出,例如wl-kbptr -O eDP-1。 - floating 自动检测不生效? 该功能需要以
opencv特性编译,运行wl-kbptr --version确认输出含opencv。 - 选错了区域? 别急,按
Backspace可逐级回退,甚至能跨模式返回。 - 想改 tile 模式的标签字符? 修改配置中
label_symbols,默认是a-z。
七、相关源码与文档路径
| 文件 | 说明 |
|---|---|
| README.md | 官方文档:模式说明、兼容性、安装与绑定示例 |
| config.example | 完整配置项示例 |
| helpers/wl-kbptr-sway-active-win | Sway 活动窗口限定脚本 |
| src/main.c | 主程序:命令行解析与 Wayland 事件循环 |
| src/mode.h | 模式接口定义(tile/bisect/split/floating/click) |
| share/wl-kbptr.desktop | 桌面入口文件 |
掌握 Sway 或 Hyprland 的这套绑定后,"键盘选鼠标"会成为你日常最高频的操作之一——装一次,爽一直 😄