10分钟上手Hyprland触摸手势:hyprgrass安装与快速入门完全指南

原创2026-11-16 09:03:381,825 阅读

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 复制到 ~/.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 的全部入门流程:

  1. ✅ 安装依赖并通过 hyprpm 完成安装
  2. ✅ 配置 sensitivity 等核心参数
  3. ✅ 掌握 swipe / edge / longpress 三种手势绑定
  4. ✅ 可选:启用音量、亮度手势

配合多指划屏切换工作区、边缘滑动呼出应用,你的 Hyprland 触摸屏桌面从此拥有媲美移动端的操作体验。更多配置细节请查阅 docs/configuration.md,项目全貌可参考 README.md。

登录后查看全文
hyprgrass