初识hyprgrass:把手机级多指触摸手势带上Hyprland

原创2026-11-15 12:07:162,212 阅读

初识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/ 目录还内置了两个"实时手势"脚本:

🚀 一键安装:三种方式任选

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/ 中的音量/亮度手势,逐步打造属于自己的"手机级"触屏桌面。

登录后查看全文
hyprgrass