hyprgrass演进史:从event hooks到emulate_touchpad触摸屏手势的完整指南

原创2026-11-16 16:00:251,941 阅读

hyprgrass演进史:从event hooks到emulate_touchpad触摸屏手势的完整指南

hyprgrass 是一款面向 Hyprland 窗口管理器的触摸屏手势插件,让你的触屏支持多指滑动、边缘滑动、长按与捏合,还能通过 emulate_touchpad 动作把触屏"伪装"成触控板。本文将带你回顾它从 event hooks 机制到 emulate_touchpad 的演进过程,并展望未来的路线图 🌱

为什么触屏需要一个手势插件?

Hyprland 的触控板原生就支持三指切换工作区、四指缩放等手势,但触摸屏一直是"空白区":手指划过去,只会点到窗口。

hyprgrass 的目标很简单——把 Wayland 生态中成熟的 wf-touch 触摸手势识别库(致谢见 README.md)搬进 Hyprland,让"三指下滑关窗口""从屏幕边缘滑出切换工作区"这类操作在触屏上一样丝滑。

核心实现由两部分组成:

阶段一:event hooks 时代

早期版本中,hyprgrass 对外暴露的是 event hooks(事件钩子):插件侦测到手势后发出事件,用户再借助外部订阅机制去触发自己的命令。

这种"先侦测、后外发"的模式直观灵活,但有一个先天短板——它只能拿到手势"完成"那一刻的结果,拿不到手势进行中的实时状态。也就是说:

  • 无法做"手指走到哪、音量条跟到哪"这类实时跟手效果
  • 事件从插件外发出去再回来执行,链路长、延迟高
  • 外部订阅方式与 Hyprland 自身日益完善的 Lua 配置体系脱节

项目内保留的 docs/event_hooks.md 如今只剩一句话:

No longer works. hyprgrass-gesture with the emulate_touchpad action is the intended replacement.

这是理解 hyprgrass 演进方向最权威的一句话:event hooks 已正式退役。

阶段二:动作系统,手势"内置化"

淘汰事件外发后,hyprgrass 转向手势动作系统:你声明"什么手势 + 什么动作",动作直接在 Hyprland 进程内执行,响应更快、状态更完整。

这一时期的配置形态(Hyprlang 风格)大致是:

# 三指下滑 → 关闭当前窗口
hyprgrass-gesture = swipe, 3, down, close

# 三指横向滑动 → 切换工作区
hyprgrass-gesture = longpress, 3, horizontal, workspace

除内置动作(workspace、close、float、fullscreen、special、move、resize)外,还支持用 hyprgrass-bind 把手势绑到任意命令。想要实时跟手效果时,官方提供了两个"活动手势"Lua 模块,可单独拷出使用(用法见 docs/configuration.md 的 Live Gesture Extras 一节):

阶段三:emulate_touchpad,让触屏"变触控板" 🎯

真正让 hyprgrass 脱胎换骨的是 emulate_touchpad 动作。

它的思路很巧妙:既然触屏缺少触控板手势,那就由插件向 Hyprland 输入系统注入标准的触控板滑动/捏合事件。你的屏幕上依然是手指,但应用程序和 Hyprland 看到的是一个"拥有四指触控板"的设备——窗口缩放、滚动、缩放动画等原生触控板行为立刻全部可用。

核心实现在 src/EmulateTouchpadGesture.hpp:它继承 Hyprland 的 ITrackpadGesture 接口,在 begin / update / end 三个回调中分别调用 g_pInputManager->onSwipeBegin、onSwipeUpdate 等接口,把触摸手势逐帧"翻译"成触控板手势。注册逻辑位于 src/main.cpp 的 emulate_touchpad 分支。

用法示例:

hl.plugin.hyprgrass.gesture {
    pattern = {kind = "edge", origin = "up", direction = "down"},
    action = "emulate_touchpad",
    emulate_fingers = 4,
    emulate_direction = "down",
}

正是这个动作让 event hooks 彻底失去了存在意义:过去要靠"外发事件 + 外部脚本"拼出来的行为,现在一行配置即可原生实现。

Lua 迁移:一次痛快的推倒重来

随着 Hyprland 全面转向 Lua 配置,hyprgrass 也完成了大迁移(当前版本 v0.8.2,见 VERSION),主要破坏性变化记录在 docs/lua_migration.md:

  1. 插件命名空间从 touch_gestures 改为 hyprgrass
  2. 旧配置项退役:workspace_swipe_fingers、workspace_swipe_edge 被统一的 hl.plugin.hyprgrass.gesture 取代(src/main.cpp 中加载配置时还会弹出弃用通知提醒你)
  3. 独立小插件合并:hyprgrass-brightnessctl、hyprgrass-pulse 两个附加载体被移除,改为上面提到的 extras/ 下的 Lua 模块
  4. 两套绑定接口定型:
    • hl.plugin.hyprgrass.bind:绑定 dispatcher(如 hl.dsp.exec_cmd),支持 tap、pinch 等模式
    • hl.plugin.hyprgrass.gesture:绑定触控板风格动作(含 emulate_touchpad)

迁移后的完整配置项与动作列表,参考 docs/configuration.md。

当前功能与未来路线图

README.md 的功能清单中,四项核心目标已全部勾选完成:

  • ✅ Workspace Swipe(滑动切换工作区)
  • ✅ Custom commands(自定义命令绑定)
  • ✅ Swipe From Edge(边缘滑动)
  • ✅ Multi-finger swipe(多指滑动)

面向未来,从代码与工程结构中可以读出几层明确的方向:

⚠️ 官方提示:项目仍处 alpha 阶段,早期版本曾有个别 bug 会在卸载插件前让触摸设备不可用,初次使用建议手边备好键盘(README.md 警告区)。

快速上手:三步装好 hyprgrass

  1. 安装依赖:Hyprland、glm,构建需要 meson 与 ninja
  2. hyprpm 一键安装:
hyprpm add https://github.com/horriblename/hyprgrass
hyprpm enable hyprgrass
  1. 调优手感(官方推荐,完整说明见 docs/configuration.md):
hl.config({
    plugin = {
        hyprgrass = {
            sensitivity = 4.0,          -- 触屏灵敏度,官方建议调高
            long_press_delay = 400,     -- 长按判定时间(ms)
        },
    },
    gestures = {
        workspace_swipe_touch = true,   -- 启用触屏三指切工作区
        workspace_swipe_cancel_ratio = 0.15,
    },
})

结语

从 event hooks 到 emulate_touchpad,hyprgrass 的演进路径其实就是一次架构思想的转变:从"把手势当信号外发"到"把手势当事件内化"。事件钩子完成了历史使命后体面退场,动作系统 + Lua 配置 + 触控板模拟的组合,让触摸屏在 Hyprland 上第一次拥有了媲美触控板的手感。随着 Hyprland Lua API 的成熟,这个仍在快速迭代中的插件,值得每一位触屏用户持续期待 👀

登录后查看全文
hyprgrass