hypr-dynamic-cursors Shake to Find 完全指南:晃动鼠标即放大,光标再也不难找
hypr-dynamic-cursors Shake to Find 完全指南:晃动鼠标即放大,光标再也不难找
快速了解 hypr-dynamic-cursors
hypr-dynamic-cursors 是一款 Hyprland 插件,核心功能正是 Shake to Find(晃动查找光标):当你在屏幕上快速来回晃动鼠标时,光标会瞬间放大数倍,晃得越久越大,让你在一堆窗口中一眼锁定鼠标位置。这个体验类似 KDE Plasma 和 macOS 的光标放大功能,但它是为 Wayland 下的 Hyprland 专门打造的。
除了找光标,它还附带了"拟真光标"玩法:光标准会像真实物体一样在 rotate(旋转)、tilt(倾斜)、stretch(拉伸)三种模式下随着移动方向产生形变。如果只想用放大功能,把 mode 设为 none 即可。
为什么你需要 Shake to Find 功能?
🤔 在 Hyprland 这种窗口自由摆放的窗口管理器里,找光标尤其困难:
- 深色壁纸 + 深色光标 = 完全隐身
- 多显示器场景下,光标可能跑到另一块屏幕上
- 小尺寸光标在大分辨率屏幕上占比极小
Shake to Find 让你只需一个自然的"急晃"动作,光标就会从原来的尺寸放大到默认 4 倍,并且持续晃动还会继续增大,直到停止晃动后 2 秒自动恢复。整个过程无需记忆任何快捷键。
一键安装步骤(hyprpm 方式)
⚠️ 插件仅支持
x86_64架构,且要求 Hyprland 版本 ≥v0.41.2。
官方推荐通过 hyprpm 安装,只需两条命令:
hyprpm add https://github.com/virtcode/hypr-dynamic-cursors
hyprpm enable dynamic-cursors
安装后重启会话即可生效。如果你使用 NixOS 或 Gentoo,仓库也提供了专门的安装途径,详见 README.md 中"installation"一节的 Nix flake / Gentoo overlay 说明。
配置安全提示
把插件相关配置放进 if 判断中,避免插件未加载时报配置错误:
if hl.plugin.dynamic_cursors then
hl.config { plugin = { dynamic_cursors = {
shake = { enabled = true }
}}}
end
最快配置方法:shake 参数逐项解析
Shake to Find 的全部配置位于 plugin.dynamic_cursors.shake 区块。默认配置即可直接用,下面是各参数的含义和调优建议:
| 参数 | 默认值 | 含义 | 调优建议 |
|---|---|---|---|
enabled |
true |
是否启用晃动查找 | 总开关 |
threshold |
6.0 |
晃动灵敏度 | 调低更容易触发,调高更"迟钝" |
base |
4.0 |
触发瞬间的放大倍数 | 觉得不够大就调高,如 6.0 |
speed |
4.0 |
持续晃动时每秒增加的放大倍数 | 配合 threshold 控制手感 |
influence |
0.0 |
晃动强度对放大速度的影响权重 | 想"越用力晃越大"就调高 |
limit |
0.0 |
放大倍数上限 | 0 表示不设上限 |
timeout |
2000 |
停止晃动后保持放大的毫秒数 | 找不准就调大到 4000 |
effects |
false |
晃动时是否同时显示 tilt/rotate 效果 | 建议保持 false,避免干扰 |
灵敏度怎么调?
检测算法会记录光标轨迹:当轨迹的总路程与活动范围对角线的比值超过 threshold,且活动范围对角线大于 100 像素时,判定为"晃动"。简单说就是——原地快速画圈或左右快速甩动最容易触发。
如果总觉得不灵敏,按这个顺序调:
- 把
threshold从6.0降到4.0左右 - 把
timeout加大到3000以上,给更多寻找时间 - 确认晃动时鼠标确实停留了足够范围(≥100px)
核心检测逻辑可以在 src/other/Shake.cpp 中查看,其中 trail / diagonal 的计算正是 KDE KWin 同款思路。
放大更清晰:hyprcursor 高分辨率支持
默认光标贴图分辨率有限,放大 4 倍后可能发虚。该插件支持通过 hyprcursor 预加载高分辨率 SVG 贴图,让放大后的光标依然锐利。相关实现在 src/highres.cpp 中。
启用条件(默认全部满足):
plugin.dynamic_cursors.hyprcursor.enabled为true- Hyprland 的
cursor.enable_hyprcursor为true - 你正在使用基于 SVG 的 hyprcursor 主题
两个常见"翻车"场景:
- XWayland 应用内依然模糊:这类应用使用客户端光标,无法替换为高清贴图。可用
hyprcursor.fallback指定一个替代形状(如fallback = "left_ptr") - 放大到极致后发糊:高清贴图是按固定尺寸预加载的,超过该尺寸就糊了。用
hyprcursor.resolution调高预加载分辨率(-1表示按光标尺寸 × shake.base计算),代价是稍高的内存和加载时间
不想晃鼠标?用快捷键直接放大
除了晃动触发,插件还内置了 dispatcher 可以让你用键盘一键放大光标,适合演示或临时找光标场景:
hl.bind("SUPER", "F2", "plugin.dynamic_cursors.dsp_magnify", { duration = 2000, size = 6.0 })
duration:保持放大的毫秒数(可选)size:放大倍数(可选)
这样设置后按 SUPER + F2,光标立即放大 6 倍并保持 2 秒。触发实现在 src/cursor.cpp 的 shake.force() 调用中。
进阶:监听晃动事件(IPC)
如果你想在晃动触发时联动其他脚本(比如弹通知、切焦点),可以开启 IPC 事件:
shake = { ipc = true }
开启后,Hyprland 事件 socket 会推送三类事件:
shakestart:晃动被检测到shakeupdate:晃动中每帧触发,附带坐标、轨迹强度、当前缩放倍数shakeend:晃动结束(timeout 之后)
⚠️ 注意晃动期间事件量很大,平时建议保持关闭。
只想放大,不要"花哨光标"?
如果你完全不需要 tilt/rotate 的拟真效果,只需要 Shake to Find,这样配置即可:
if hl.plugin.dynamic_cursors then
hl.config { plugin = { dynamic_cursors = {
enabled = true,
mode = "none", -- 关闭所有拟真形变
shake = { enabled = true }
}}}
end
三种模式简介(来自 README.md):
rotate:光标像一根被拖动的杆子,朝移动方向旋转,最逼真tilt:按水平速度倾斜,模拟空气阻力,默认模式stretch:按速度拉伸变形,漫画感拉满
性能与兼容性注意事项
📌 使用前请留意这几点(详见 README.md 的 performance / compatibility 章节):
- 软件光标:无额外性能损耗
- 硬件光标:有中等性能损耗;放大时会自动临时切换回软件光标
- NVIDIA 显卡:因驱动限制,插件会自动强制使用软件光标
- XWayland 应用:光标形变规则(shape rules)对其无效
- 项目仍处于早期开发阶段,作者不承诺长期维护,欢迎贡献代码
常见问题速查(FAQ)
Q:晃鼠标没有反应,光标不放大?
A:检查 shake.enabled 是否为 true;确认在 Hyprland 会话内而非 X11 会话;把 threshold 调低;确认晃动幅度大于 100 像素。
Q:如何彻底关闭 Shake to Find?
A:设置 shake.enabled = false 即可,插件其余功能不受影响。
Q:放大倍数上限怎么设?
A:默认 limit = 0.0 即无上限(持续晃会一直变大)。想封顶就设 limit = 8.0 之类的值,注意低于 1 的值会被视为禁用上限。
Q:配置改完不生效?
A:改完 hyprland.lua(或对应配置文件)后重新加载配置或重启会话;插件配置支持热重载,但若配置语法错误会被忽略,可用 hyprctl 检查报错。
总结
hypr-dynamic-cursors 用不到 10 行配置就为 Hyprland 补上了 Wayland 世界长期缺失的 Shake to Find 体验:晃一下,光标放大 4 倍起步,越晃越大,停晃 2 秒后自动还原。配合 hyprcursor 高清贴图和 dispatcher 快捷键,找光标这件事从此彻底消失。装上它,你的 Hyprland 会立刻好用一个档次 ✨