wl-kbptr键盘选鼠标:Sway与Hyprland快捷键绑定2合1实战教程

原创2026-10-28 18:04:131,819 阅读

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 的这套绑定后,"键盘选鼠标"会成为你日常最高频的操作之一——装一次,爽一直 😄

登录后查看全文
wl-kbptr