10分钟上手Hyprland触摸手势:hyprgrass安装与快速入门完全指南
10分钟上手Hyprland触摸手势:hyprgrass安装与快速入门完全指南
想在 Hyprland 桌面上用触摸手势像手机一样划屏切换工作区吗?本文带你用 10 分钟完成 hyprgrass 的安装与配置。hyprgrass 是一款专为 Hyprland 打造的触摸屏手势插件,让你获得多指滑动、边缘手势、长按等完整的触控体验。
🤔 hyprgrass 是什么?
hyprgrass 是一个 Hyprland 插件,它为触摸屏带来类似移动端的手势操作能力。核心功能包括:
- 工作区滑动(Workspace Swipe):多指左右滑动切换工作区
- 自定义命令(Custom Commands):任意手势绑定任意操作
- 边缘滑动(Swipe From Edge):从屏幕边缘发起手势
- 多指滑动(Multi-finger Swipe):支持任意指数的复杂手势
插件主入口源码位于 src/main.cpp,手势核心逻辑在 src/gestures/Gestures.cpp 中实现。
⚠️ 重要提示:hyprgrass 目前仍处于 alpha 阶段,首次使用时请手边备好键盘,以防手势冲突导致临时无法操作屏幕。
📦 安装前准备:依赖检查
在安装之前,确保系统已安装以下依赖:
| 依赖 | 用途 |
|---|---|
| Hyprland | 桌面环境(前提) |
glm |
数学运算库 |
meson + ninja |
构建工具 |
🚀 hyprgrass 最快安装方式:hyprpm 一键安装
推荐使用 hyprpm 插件管理器安装,只需两条命令:
hyprpm add https://gitcode.com/gh_mirrors/hy/hyprgrass
hyprpm enable hyprgrass
再在 Hyprland 配置中添加以下行,让插件在开机时自动加载(-n 参数会在出问题时发送通知):
exec-once = hyprpm reload -n
Nix Flakes 安装方式
如果你使用 Nix 管理环境,将 hyprgrass 加入 flake.nix 的 inputs 即可,参考仓库自带的 flake.nix 和 nix/default.nix:
hyprgrass = {
url = "github:horriblename/hyprgrass";
inputs.hyprland.follows = "hyprland"; # IMPORTANT
};
手动编译安装
适合想参与调试或需要 debug 构建的用户:
git clone https://gitcode.com/gh_mirrors/hy/hyprgrass
cd hyprgrass
meson setup build
ninja -C build
编译产物为 build/src/libhyprgrass.so(见 hyprpm.toml),可通过 hyprctl plugin load 加载。开发者还可用 scripts/hotreload 脚本实现插件热重载,无需重启 Hyprland。
⚙️ hyprgrass 基本配置:灵敏度是最关键的一步
hyprgrass 使用 Lua 配置。在 hyprland.lua 中添加:
hl.config({
plugin = {
hyprgrass = {
sensitivity = 4.0, -- 平板屏幕建议调到 4.0
long_press_delay = 400, -- 长按判定时间(毫秒)
resize_on_border_long_press = true,
edge_margin = 10, -- 边缘判定距离(像素)
}
}
})
💡 新手建议:默认灵敏度在平板屏幕上偏小,调到 4.0 手感明显更跟手。同时开启内置的工作区滑动更顺滑:
hl.config({
gestures = {
workspace_swipe_touch = true,
workspace_swipe_cancel_ratio = 0.15,
},
})
完整配置项说明见 docs/configuration.md。
🖐 三种手势模式:swipe、edge、longpress
hyprgrass 提供两种绑定 API,新手记住"三种手势模式"即可上手:
| 模式 | 写法 | 含义 |
|---|---|---|
| 普通滑动 | {kind = "swipe", fingers = 3, direction = "down"} |
任意位置三指下滑 |
| 边缘滑动 | {kind = "edge", origin = "right", direction = "vertical"} |
从右边缘竖向滑动 |
| 长按 | {kind = "longpress", fingers = 3} |
三指长按 |
此外还支持点按(tap)和捏合(pinch)两种模式,详见 docs/configuration.md。
方式一:hyprgrass.gesture(绑定内置动作)
最简单的方式,直接对接 Hyprland 内置手势动作:
-- 三指下滑关闭窗口
hl.plugin.hyprgrass.gesture {
pattern = {kind = "swipe", fingers = 3, direction = "down"},
action = "close",
}
方式二:hyprgrass.bind(绑定任意命令)
功能更强大,可以把手势绑定到任意 dispatcher,包括鼠标操作:
-- 底部边缘两指上滑,启动浏览器
hl.plugin.hyprgrass.bind {
pattern = {kind = "edge", origin = "d", direction = "u", fingers = 2},
action = hl.dsp.exec_cmd("firefox"),
}
-- 三指点按切换窗口浮动
hl.plugin.hyprgrass.bind {
pattern = {kind = "tap", fingers = 3},
action = hl.dsp.window.float(),
}
🔊 进阶玩法:手势控制音量与亮度
项目 extras/ 目录内置了两个现成的 Lua 手势模块,非常实用:
- extras/wpctl.lua:通过手势调节音量(基于
wpctl) - extras/brightnessctl.lua:通过手势调节屏幕亮度(基于
brightnessctl)
以音量为例,把 extras/wpctl.lua 复制到 ~/.config/hypr/plugins/hyprgrass/extras/ 后,在配置中这样使用——右边缘竖向滑动即可实时调音量:
local wpctl = require("plugins.hyprgrass.extras.wpctl")
hl.plugin.hyprgrass.gesture {
pattern = {kind = "edge", origin = "right", direction = "vertical"},
action = wpctl.volume_action({direction = "vertical", flip = true}),
}
❓ 常见问题与注意事项
Q:加载插件后触摸没反应怎么办?
先检查 sensitivity 是否调高,再确认手势 fingers 数量与你的实际指头数一致。
Q:遇到崩溃如何反馈?
崩溃日志位于 ~/.cache/hypr/hyprlandCrashReport{pid}.txt,建议用 debug 构建(meson setup build -Dbuildtype=debug)获取更详细的堆栈信息。
Q:如何热重载插件方便调试?
使用仓库自带脚本:scripts/hotreload ./build/src/libhyprgrass.so。
Q:从旧版 hyprlang 配置迁移?
参考 docs/lua_migration.md,主要变化是插件命名空间从 touch_gestures 改为 hyprgrass。
🎯 小结
至此你已经完成了 hyprgrass 的全部入门流程:
- ✅ 安装依赖并通过 hyprpm 完成安装
- ✅ 配置
sensitivity等核心参数 - ✅ 掌握 swipe / edge / longpress 三种手势绑定
- ✅ 可选:启用音量、亮度手势
配合多指划屏切换工作区、边缘滑动呼出应用,你的 Hyprland 触摸屏桌面从此拥有媲美移动端的操作体验。更多配置细节请查阅 docs/configuration.md,项目全貌可参考 README.md。