跳到主要内容
macOS 工具

mac_touchpad · 触控板手势

双击触控板边缘并保持滑动,就能调系统音量、亮度或媒体进度;每滑一格给一次刻度震动。整个手势行为是一张可以自己连线的节点图。

SwiftmacOS私有框架手势引擎MIT
平台
macOS 15+(内置触控板)
语言
Swift 5 / SwiftUI + AppKit
状态
可下载的 Release
GitHub
8 star · MIT

01起点

笔记本上调音量要么去按 F 键,要么点菜单栏,都要离开当前操作。但手指大多数时候本来就在触控板上。所以我想:能不能「按在边缘往下滑」就调音量,而且滑动手感像真的有个旋钮?

做出来之后手感成了主要工作:不是把值改掉就完事,而是要有一格一格的刻度、要到边就停住、要按压力度分档、要在调节期间锁住光标不乱跑。

02怎么拿到触控板数据

  • 走 MultitouchSupport.framework(Apple 私有框架),dlopen / dlsym 动态加载,绕开 ARM64e 的指针认证,拿每根手指 96 字节的原始触摸结构。
  • 写了一个 C 桥接层负责设备发现、触摸回调与触觉反馈,并对私有回调里的 n_fingers 做边界钳制(它真的会越界)。
  • 取设备 ID 时踩了个坑:在 Apple Silicon 上调 MTDeviceGetDeviceID() 会直接 SIGBUS。改成从 MTDevice 结构偏移 64 处读,再用 IORegistry 的 mt-device-id 交叉校验。

03手势是一张图,不是一个 if

第一版把「双击 + 保持 + 滑动」写死成状态判断,很快就改不动了:想加一个 Force 按压触发、想把滑动的量化改成非线性、想在某一步加一次震动,都要动主逻辑。于是重写成 节点图执行引擎:识别状态机、信号管线、反馈动作全部是图上的节点。

  • 编辑器和 Blender 的节点编辑器一个路子:折叠模块、自动整理、框选复制粘贴。高层设置页与画布双向同步,不想连线的人也能用。
  • 采用摩尔状态机语义:帧首读旧值、帧尾统一写,状态转移用旧状态判断、新状态下一帧才生效——避免同一帧里的顺序依赖。
  • 固定步长帧循环:活跃期 120Hz,确认空载后降到 20Hz 省电,触摸一到立刻恢复全速。
  • 还有一层「快照陈旧判定」:回调停止超过阈值就当作手指离开,喂空帧把状态机拉回 idle。否则冻结帧会让引擎以 120Hz 空转且永不自愈。

04震动不是装饰

触觉反馈决定了「这是不是个旋钮」。预设波形只有几个,所以我做了自定义波形:包络 + 音调(Sine / Square)+ 力度乘法器(Light / Medium / Firm 各档缩放),编辑时实时试听。

实现上走私有 MTActuationCreateFromDictionary 编译波形,用 waveformID 83 的自定义槽位下发,与 Apple 的预设波形互不干扰。如果某机型/系统缺这个符号,自动回退到预设波形——任何情况下都要有反馈,而不是静默失效。

05不联网,也不乱写盘

  • App 不发任何网络请求,配置只存在 ~/Library/Application Support/TouchpadGestures/。
  • 配置解析失败时隔离备份为 config.corrupt-<时间戳>.json 并告警,绝不原地丢弃。
  • 拖滑杆这类连续编辑合并成 300ms 一次落盘,退出时强制刷盘。
  • 解码时顺手去重节点 id、清理悬空边——重复 id 是会崩的。

06边界与风险

用私有框架就注定和系统更新赌运气:任何一次 macOS 更新都可能改结构偏移或函数签名。App 是 ad-hoc 签名(没有开发者证书),首次打开要右键 →「打开」;也正因为这样,它不适合上 App Store,定位是自用工具。

主站