让触摸屏变身触控板:hyprgrass emulate_touchpad 动作完全指南
让触摸屏变身触控板:hyprgrass emulate_touchpad 动作完全指南
hyprgrass 是 Hyprland 的触摸屏手势插件,它的 emulate_touchpad 动作能把普通触摸屏"变成"一块触控板:用多指滑动切换工作区、移动/缩放窗口、进出全屏,操作手感与你熟悉的手掌触控板几乎一致。本指南带你从安装到常用配置一步步搞定。
一、emulate_touchpad 是什么
emulate_touchpad 是 hyprgrass 独有的手势动作(action)。它的作用是:把你在触摸屏上做出的手势,"翻译"成 Hyprland 原生的触控板手势事件,从而复用系统内置的触控板功能(工作区切换、窗口缩放、缩放级别调整等)。
它的核心逻辑位于 src/EmulateTouchpadGesture.hpp。实现上它监听手势的 begin / update / end 三个阶段,并调用 Hyprland 的输入管理器 onSwipeBegin、onPinchUpdate 等接口,把触摸事件无缝转发出去,因此体验非常自然。
💡 简单理解:触摸板能"滑动切换工作区",触摸屏也能通过
emulate_touchpad获得同样的能力。
二、前置准备:安装 hyprgrass
emulate_touchpad 依赖插件本身已加载,先确认安装完成。
1. 安装依赖(除 Hyprland 外需要 glm、meson、ninja)
2. 通过 hyprpm 安装并启用插件
hyprpm add https://github.com/horriblename/hyprgrass
hyprpm enable hyprgrass
3. 让插件开机自动加载:在 Hyprland 配置中加入
exec-once = hyprpm reload -n
安装说明详见 README.md。
三、快速上手:一条配置让触摸变触控板
在 Lua 配置(~/.config/hypr/hyprland.lua)中用 hl.plugin.hyprgrass.gesture 绑定即可。下面这段让三指水平滑动触发工作区切换:
hl.plugin.hyprgrass.gesture {
pattern = {kind = "swipe", fingers = 3, direction = "horizontal"},
action = "emulate_touchpad",
emulate_fingers = 3,
emulate_direction = "horizontal",
}
保存并重新加载配置后,三指左右滑动即可像触控板一样切换工作区。
四、完整参数详解
emulate_touchpad 在 pattern、action 之外,额外接受两个参数:
| 参数 | 说明 | 示例取值 |
|---|---|---|
emulate_fingers |
模拟触控板手势时使用的"手指数" | 2、3、4 |
emulate_direction |
模拟触控板手势的方向 | left / right / up / down / horizontal / vertical / pinchin / pinchout |
其中 emulate_fingers 决定系统把它识别为几指触控板手势(如 3 指滑动 = 工作区切换,2 指滑动 = 页面滚动),取值规则与 Hyprland 官方手势文档一致。
手势模式 pattern 常用字段:
kind = "swipe":普通多指滑动,需指定fingers与directionkind = "edge":从屏幕边缘起手,需指定origin(起点边)与directionkind = "pinch":双指捏合,需指定fingers与direction(pinchin/pinchout)kind = "longpress":长按
⚠️ 小提示:部分动作(如
workspace)不接受"swipe"这种"任意滑动"方向,请为它们指定具体方向;scale(0.1 起步)可调高动画速度,mod可叠加键盘修饰键。
五、常用场景配置示例
从顶部边缘向下滑动 → 打开 Special 工作区:
hl.plugin.hyprgrass.gesture {
pattern = {kind = "edge", origin = "up", direction = "down"},
action = "emulate_touchpad",
emulate_fingers = 4,
emulate_direction = "down",
}
三指下滑 → 模拟触控板三指下滑(常用于关闭窗口/页面):
hl.plugin.hyprgrass.gesture {
pattern = {kind = "swipe", fingers = 3, direction = "down"},
action = "emulate_touchpad",
emulate_fingers = 3,
emulate_direction = "down",
}
📌
emulate_direction应与pattern的direction保持一致,这样"你划的方向"就是"触控板手势的方向",手感最直观。
六、旧版 hyprlang 写法对照
如果你仍在使用传统 hyprlang 配置,等价的单行写法如下(格式:hyprgrass-gesture = 手势, 手指数, 方向, 动作, 模拟手指数, 模拟方向):
hyprgrass-gesture = swipe, 3, down, emulate_touchpad, 3, down
从 hyprlang 迁移到 Lua 的字段对照,可参考 docs/lua_migration.md。
七、常见问题与排查
- 动作不生效:确认插件已通过
hyprpm enable hyprgrass启用,且配置写在hyprland.lua而非纯 hyprlang 文件。 - 参数报错
unknown action "emulate_touchpad":说明拼写错误——它必须完整写作emulate_touchpad,完整动作分发表在 src/main.cpp。 - 日志出现
inconsistent gesture isPinch values:表示emulate_direction的捏合属性与手势本身不匹配(例如手势是 swipe 却给了pinchin),把两者对齐即可。 - 灵敏度不合适:在
hl.config({plugin = {hyprgrass = {sensitivity = 4.0}}})中调整灵敏度,平板屏幕建议调高。
写在最后
emulate_touchpad 让 hyprgrass 把"触摸手势"和"触控板手势"打通,是触摸屏用户最实用的功能之一。更多动作与参数说明,请查看官方配置文档 docs/configuration.md 中的 emulate_touchpad 章节。
🎉 现在,你的触摸屏已经是一块会切换工作区、会缩放的触控板了!