初识hyprgrass:把手机级多指触摸手势带上Hyprland
初识hyprgrass:把手机级多指触摸手势带上Hyprland
hyprgrass 是一款专为 Hyprland 窗口管理器打造的触摸屏多指手势插件,让触屏设备(平板、触控屏笔记本、二合一电脑)获得类似手机的多指滑动、边缘手势、捏合、长按等能力。只需几行 Lua 配置,三指下滑关闭窗口、边缘滑动切换工作区、长按边框调整大小就能在桌面上实现,把"手机手感"搬进 Linux 桌面。
📌 hyprgrass 能做什么?功能一览
根据 README.md 中的功能清单,hyprgrass 已支持以下核心能力:
| 功能 | 说明 | 使用场景 |
|---|---|---|
| 多指滑动(swipe) | 2/3/4 指滑动触发任意动作 | 三指下滑关闭窗口、切换工作区 |
| 边缘滑动(edge) | 从屏幕边缘特定方向滑出 | 下滑查看 Special 工作区、边缘调音量 |
| 长按(longpress) | 多指长按窗口 | 拖动、调整窗口大小 |
| 轻点(tap)与捏合(pinch) | 多指轻点、捏合缩放 | 三指轻点切换悬浮、捏合打开应用 |
| 模拟触控板(emulate_touchpad) | 把触摸手势转成触控板手势 | 触屏设备获得触控板体验 |
| 自定义命令(bind) | 手势绑定任意 Hyprland dispatcher | 按手势启动 firefox、终端等 |
此外,extras/ 目录还内置了两个"实时手势"脚本:
- extras/wpctl.lua:滑动调音量(依赖 WirePlumber 的
wpctl) - extras/brightnessctl.lua:滑动调屏幕亮度(依赖
brightnessctl)
🚀 一键安装:三种方式任选
hyprgrass 基于 Hyprland 插件 API 开发,需要预先安装依赖库 glm 以及构建工具 meson、ninja。
方式一:hyprpm 安装(推荐新手)
在 Hyprland 中运行插件管理器 hyprpm,两条命令即可完成:
hyprpm add https://gitcode.com/gh_mirrors/hy/hyprgrass
hyprpm enable hyprgrass
建议在 Hyprland 配置中加上 exec-once = hyprpm reload -n,让插件随桌面启动自动加载(-n 参数会在需要更新时发出通知)。
方式二:Nix Flakes 安装
Nix 用户可以把 hyprgrass 加进 flake.nix 的 inputs 中,注意将 hyprland 输入 follows 到主 Hyprland 版本,避免版本冲突;随后在 home-manager 模块的 wayland.windowManager.hyprland.plugins 中加入 inputs.hyprgrass.packages.${pkgs.system}.default 即可。详见 flake.nix 与 nix/default.nix。
方式三:从源码手动编译
想体验开发版或调试崩溃时,可以手动编译:
git clone https://gitcode.com/gh_mirrors/hy/hyprgrass
cd hyprgrass
meson setup build
ninja -C build
hyprctl plugin load "$PWD/build/src/libhyprgrass.so"
💡 插件输出产物为
build/src/libhyprgrass.so(见 hyprpm.toml),加载后即可在会话中生效。
⚙️ 快速上手:基础配置 4 个关键参数
hyprgrass 使用 Hyprland 的 Lua 配置(hyprland.lua)。以下是最常用的全局参数,完整说明见 docs/configuration.md:
hl.config({
plugin = {
hyprgrass = {
sensitivity = 4.0, -- 触控屏灵敏度,平板建议调到 4.0
long_press_delay = 400, -- 长按判定延迟(毫秒)
resize_on_border_long_press = true, -- 长按窗口边框/间隙调整大小
edge_margin = 10, -- 距边缘多少像素算"边缘"
}
}
})
📝 新手提示:作者特别指出默认灵敏度对平板屏幕偏低,建议把 sensitivity 调到 4.0;同时开启内置手势以方便切换工作区:
hl.config({
gestures = {
workspace_swipe_touch = true,
workspace_swipe_cancel_ratio = 0.15,
},
})
🎯 手势绑定实战:两条 API 覆盖所有场景
hyprgrass 提供两个绑定函数(语法详情见 docs/configuration.md):
hl.plugin.hyprgrass.bind:把手势绑定到任意 dispatcher,支持启动程序、鼠标动作等hl.plugin.hyprgrass.gesture:把手势绑定到 Hyprland 内置触控板手势动作(workspace、close、float、special 等)
场景 1:三指下滑关闭当前窗口
hl.plugin.hyprgrass.gesture {
pattern = {kind = "swipe", fingers = 3, direction = "down"},
action = "close",
}
场景 2:屏幕底边边缘滑动切换工作区
hl.plugin.hyprgrass.bind {
pattern = {kind = "edge", origin = "d", direction = "l"},
action = hl.dsp.focus({workspace = "+1"}),
}
场景 3:三指捏合打开终端、三指轻点悬浮窗口
hl.plugin.hyprgrass.bind {
pattern = {kind = "pinch", fingers = 3, direction = "pinchin"},
action = hl.dsp.exec_cmd("foot"),
}
hl.plugin.hyprgrass.bind {
pattern = {kind = "tap", fingers = 3},
action = hl.dsp.window.float(),
}
场景 4:模拟触控板手势
有触控板的用户可以用触屏手势模拟触控板动作,例如把三指下滑转成触控板三指下滑:
hl.plugin.hyprgrass.gesture {
pattern = {kind = "swipe", fingers = 3, direction = "down"},
action = "emulate_touchpad",
emulate_fingers = 3,
emulate_direction = "down",
}
📌 旧版基于 Hyprlang 的
hyprgrass-gesture/hyprgrass-bind配置语法已迁移到 Lua,从旧版本升级请阅读 docs/lua_migration.md,注意插件命名空间由touch_gestures改为hyprgrass。
🎚 进阶:滑动调节音量与亮度
复制 extras/wpctl.lua 到 ~/.config/hypr/plugins/hyprgrass/extras/ 目录,然后在 hyprland.lua 中:
package.path = package.path .. ";/home/USER/.config/hypr/?.lua;/home/USER/.config/hypr/?/init.lua"
if hl.plugin.hyprgrass then
local hg_wpctl = require("plugins.hyprgrass.extras.wpctl")
hl.plugin.hyprgrass.gesture({
pattern = {kind = "edge", origin = "right", direction = "vertical"},
action = hg_wpctl.volume_action({
direction = "vertical",
flip = true, -- 反转滑动方向
})
})
end
配置后,从屏幕右侧垂直滑动即可调节系统音量。亮度调节同理,替换为 extras/brightnessctl.lua。
📂 项目结构导览:了解 hyprgrass 内部
如果你感兴趣,可以快速扫一眼核心代码结构(贡献指南见 CONTRIBUTING.md):
| 模块 | 路径 | 作用 |
|---|---|---|
| 手势定义接口 | src/gestures/Gestures.hpp | IGestureManager,处理触摸事件并触发手势 |
| 事件处理器 | src/GestureManager.hpp | 实现 Hyprland 侧的事件回调 |
| 动作链实现 | src/gestures/Actions.cpp | 自定义 action_t,串联触摸事件序列 |
| 单元测试 | src/gestures/test/ | 手势检测逻辑的独立测试 |
| 构建选项 | meson_options.txt | 控制测试开关与插件构建 |
手势检测的数学核心来自 Wayfire 项目的 wf-touch 库,位于 subprojects/wf-touch/,这让 hyprgrass 能可靠识别滑动、捏合等复杂轨迹。
⚠️ 新手避坑指南:常见问题与注意事项
1. 首次使用请备好键盘 README 中明确提醒:插件历史上曾有过会导致触摸设备"卡死"的 bug(需卸载插件或重启 Hyprland 恢复),当前版本虽然基本稳定但仍属 alpha 阶段,首次体验时手边放好键盘最保险。
2. Hyprland 版本需要匹配 hyprgrass 与 Hyprland 版本强绑定,hyprpm.toml 中维护了完整的 commit 对照表(从 v0.40.0 到 v0.56.x)。升级 Hyprland 后若插件加载失败,大概率是版本不匹配,等待 hyprgrass 跟进即可。
3. 旧事件钩子已弃用
docs/event_hooks.md 声明旧版事件钩子机制已不再工作,官方推荐用 hyprgrass-gesture 的 emulate_touchpad 动作替代。
4. 触屏好搭档 README 还推荐了几款配套工具:squeekboard / wvkbd(屏幕键盘)、iio-hyprland(自动屏幕旋转)、Hyprspace(窗口总览)、nwg-drawer(应用抽屉),配合 hyprgrass 能让触屏桌面体验更完整。
📚 写在最后
hyprgrass 用不到几十行配置,就把"三指下滑关闭窗口""边缘滑动切工作区""捏合呼出应用"这些手机上的肌肉记忆带到了 Hyprland 桌面。对于拥有触控屏的 Linux 用户来说,它是把"能用鼠标"变成"好用手指"的关键一步。
推荐学习路径:先按本文完成安装与基础灵敏度设置 → 阅读 docs/configuration.md 掌握 bind 与 gesture 两种绑定 → 按需添加 extras/ 中的音量/亮度手势,逐步打造属于自己的"手机级"触屏桌面。