Tinycast 全局快捷键完全指南录制、双击修饰键与 Hyper 键的实现细节【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycastTinycast 是一款完全原生的 macOS 启动器、热键与剪贴板历史工具其全局快捷键系统开箱即无绑定——每一个快捷键都由你自己录制。本文基于 Hotkeys 参考文档 与 Features/HotKeys 源码目录完整讲解可绑定对象、录制交互、双击修饰键Double-Tap与 Hyper 键的精确规则与底层实现读完后你将能熟练配置任意全局快捷键并理解录制零权限、辅助功能按需授权的设计逻辑。开箱即无绑定一切快捷键由你录制Tinycast 出厂时不绑定任何全局快捷键。所有快捷键都是你在设置界面中录制出来的。这一设计避免了与系统或其他应用抢占组合键的默认冲突也让每个用户只保留自己真正需要的按键映射。录制完成后的快捷键会在两个地方呈现在对应设置的行内显示Settings 中该项所在的行带有快捷键录制器在launcher 行上以键帽keycap形式展示例如⌃⌥⌘G会显示为键帽序列。另外一个打开屏幕的命令天然是开关toggle按一次快捷键打开对应屏幕再按一次关闭它。从源码看所有这类命令统一经由PaletteCoordinator.togglePalette(mode:)进入因此第二次按下天然触发关闭见 docs/features/hotkeys.md 的不变式说明。什么可以拥有快捷键Tinycast 的全局快捷键覆盖面很广以下是完整的可绑定对象清单可绑定对象说明Palette 本身App Launcher位于 Settings → General是唯一一个没有独立命令行的固定动作源码中对应hotkey.togglePalette见 HotKeyAction.swift每个内置命令除 Open in Browser、Run Shell Command 与 Quit Tinycast 之外的命令全部可绑定详见 Commands每个应用、每个系统设置面板通过 bundle ID 索引每个 quicklink、自定义命令、自定义 Quick Action 与扩展命令通过稳定 UUID 索引全部 31 个系统动作锁定屏幕、睡眠、重启、音量、蓝牙、废纸篓等清单见 System actions全部 35 个窗口命令与每个窗口布局见 window-management 与 window-layouts从源码结构看HotKeyAction枚举完整描述了这一切见 HotKeyAction.swifttogglePalette、command(CommandID)、app(bundleID:)、settingsPane(bundleID:)、customCommand(id:)、systemAction(id:)、windowCommand(id:)、windowLayout(id:)、customWindowSize(id:)、quicklink(id:)、quickAction(id:)、appleShortcut(id:)与extensionCommand(entryID:)。内置命令为什么只有三个例外CommandID.hotKeyAction默认对每个命令回答.command(self)并显式排除三个Open in Browser 与 Run Shell Command 是查询驱动型命令——它们的输入来自你键入的文本而一个和弦chord快捷键没有任何文本可以传递Quit Tinycast 被刻意隐藏以免任何误触直接退出应用。这是一个拒绝列表deny-list而非允许列表意味着未来新增内置命令时无需改动快捷键模块即可自动获得可绑定能力见 docs/features/hotkeys.md。录制一个快捷键快捷键录制器不是普通的文本输入框。正确的操作方式是先点击录制器字段然后按下你想要的按键组合而不是去打字。录制过程中字段上方会弹出一个小的提示气泡它按顺序展示三类信息提示文案引导你按下按键你当前按住的修饰键实时预览便于确认自己按对了冲突警告如果该快捷键已被占用会指名道姓地告诉你具体是哪个功能/命令在使用它。录制本身不需要任何权限。只有使用某些类型的快捷键才需要权限见下文双击修饰键与 Hyper 键部分。从实现上看录制器Features/HotKeys/UI/ShortcutRecorder.swift刻意不是一个可聚焦控件当前正在录制的动作由HotKeyManager.recordingAction状态标识按键通过本地 NSEvent 监听捕获同时两套引擎Carbon 热键注册与双击监听都会被暂停避免录制过程中触发已有绑定。它把.flagsChanged/.keyDown监听喂给与全局监听同一个DoubleTapDetector所以录制时既不需要事件 tap 也不需要权限见 docs/features/hotkeys.md 的 Recorder 一节。应用内只存在一个ShortcutCaptureSession实例而非每行一个这正是气泡能渲染实时录制状态的原因——提示、实时预览与冲突消息全部位于气泡内字段本身只展示最终绑定结果。双击修饰键Double-Tap Modifiers任何快捷键都可以换成某个单独修饰键的双击——⌃、⌥、⇧或⌘之一。Carbon API 根本无法注册仅修饰键的快捷键因此这是一套独立的引擎仅在HotKeyBinding这一层与普通组合键汇合见 HotKeyBinding.swift。精确规则双击的判定规则非常严格文档给出了三条硬性定义一次 tap恰好按下这四个修饰键中的一个没有其他键、其他修饰键也没有点击鼠标并在250 ms内释放。一次 double tap在第一次释放后的300 ms 内再次开始按下同一个键。触发时机是第二次释放而不是第二次按下。动作运行时修饰键已经抬起——这意味着 palette 打开时不会残留一个幽灵 ⌘焦点恢复也不会被污染同时双击并按住被刻意设计为无动作。⇧可以作为双击键使用即使单独的⇧不能作为普通快捷键因为裸 ⇧ 组合会与打字产生歧义Caps Lock 不能用于双击——那是 Hyper 键的职责。值得注意的细节是Caps Lock 处于开启状态并不会妨碍双击判定。源码将这三条规则精确落为常量见 DoubleTapDetector.swift/// Longest a press may last and still be a tap; matches HyperKeyTap.quickPressWindow. static let maxHold: TimeInterval 0.25 /// Longest gap between the first taps release and the second taps press. static let maxGap: TimeInterval 0.30DoubleTapDetector保持纯 Foundation 实现、时钟以参数注入now为调用方提供的单调时间戳因此 Tests/hotkey-test.swift 可以在不创建任何事件 tap 的情况下驱动它做边界测试。测试覆盖了完整的行为契约单次 tap 不触发、第二次释放才触发firing、慢于窗口的按压不算 tap、超出 300 ms 间隔不触发、三连击只触发一次、两次不同修饰键不构成双击、按下期间夹带其他按键或鼠标点击会取消配对等timing、chords、interruptions。权限与成本双击修饰键需要辅助功能Accessibility权限但从不主动申请。快捷键照样保存录制器会显示一个打开系统设置的警告授权生效的那一刻快捷键立即开始工作。另一个成本细节只有当至少一个快捷键使用了双击绑定时Tinycast 才会开启双击监听。如果你从未使用双击系统不会为它付出任何代价。DoubleTapMonitor是一个只读listen-only的 CGEventTap并且只在绑定集合非空时才安装事件 tap见 DoubleTapMonitor.swift。该监听器还有两个负载关键的实现细节它是.tailAppendEventTap区别于 Hyper 键与剪贴板等头部插入的 tap因此它观察的是Hyper 键重写之后的事件流——被 Hyper 重映射的右侧修饰键会以完整 ⌃⌥⇧⌘ 和弦到达被正确判定为不是单独修饰键而左侧对应键仍可正常双击它通过一个每秒一次的看门狗持续重试安装权限授予后无需重启即可生效快速用户切换时会暂停监听直到当前会话重新激活见 docs/features/hotkeys.md。Hyper 键Settings → General → Hyper Key可以把一个物理键转换成⌃⌥⌘和弦开启Include Shift后则变为⌃⌥⇧⌘。可选的物理键有五种对应源码 HyperKey.swift 中的枚举选项源码枚举值Caps Lock (⇪)capsLockRight Control (⌃)rightControlRight Shift (⇧)rightShiftRight Option (⌥)rightOptionRight Command (⌘)rightCommand功能键F1–F20不在候选之列顶部媒体功能键的事件在 Tinycast 能看到之前就已经被系统消费——把 F1 变成 Hyper 键后按它仍然会调暗屏幕媒体亮度功能照常触发。你已经配置的、包含这些修饰键的快捷键会立即与 Hyper 键协同工作无需重新录制。原理上HyperKeyTap是一个修改型modifyingCGEventTap与HotKeyCenter是相互独立的层它把按下 Hyper 键期间的所有事件重写为带完整和弦 flags 的事件重写后的 flags 继续流入 Carbon 匹配层因此既有组合键热键无需额外注册即可从Hyper键触发见 docs/features/hotkeys.md。✦ 符号书写方式而非设置项任何包含全部 Hyper 修饰键的快捷键都会显示为单个 ✦。例如⌃⌥⌘G显示为✦G如果还叠加了额外的修饰键如 ⇧则显示为✦⇧G。这只是书写方式不是可配置项——把 Hyper 和弦折叠为 ✦ 正是这个功能本身的意义。唯一的条件是必须配置了 Hyper 键未配置时⌃⌥⌘G会原样显示为四个修饰键加字母见 docs/features/hotkeys.md。源码中折叠逻辑位于 KeyShortcut.swift当 flags 是 Hyper 和弦的超集时用✦替换和弦部分并保留剩余修饰键displayedHyperChord是一个闭包而非值读取它会在视图体中注册AppSettings依赖因此切换设置时所有键帽即时重渲染。Include Shift重指向已保存的快捷键切换Include Shift会更新每一个已保存的快捷键确保没有任何绑定失效。原因在于KeyShortcut保存的是录制瞬间的绝对 Carbon 修饰键——在一种 Include Shift 设置下录制的和弦在另一种设置下会同时失去 ✦ 折叠效果和实际触发能力Carbon 注册的是 ⌃⌥⌘而 tap 已开始输出 ⌃⌥⇧⌘。因此切换开关时HotKeyManager.retargetHyperBindings会把每个已存组合键中的旧和弦替换为当前和弦见 HotKeyManager.swift。如果某个重指向会与另一快捷键冲突那一项会被跳过并保留原始按键而不是覆盖掉冲突方。重指向操作是幂等的idempotent这让设置导入成为无副作用操作而不是损坏源。当 Hyper Key 设为 None 时该选项置灰——没有和弦可指向自然无法移动。Quick Press单独按下 Hyper 键时做什么Settings → General → Quick Press决定单独快速按下 Hyper 键没有与其他键组合时的行为选项行为Does Nothing默认什么也不做The keys original job触发该键原本的功能仅对 Caps Lock 提供即Trigger Caps Lock (⇪)Trigger Escape触发一次 EscapeEscape 是 Caps Lock 用户最常选的一项——把 Caps Lock 变成 Hyper 键后单独快速按一下就能当作 Esc 使用这也是许多 Vim/终端用户的习惯配置。从实现看HyperKeyTap.swift按住开始计时若在 250 ms与双击 tap 的窗口一致内释放且期间没有按下其他键则判定为 quick press并延迟到下一个 runloop 回合再投递事件——在 tap 回调内部直接投递事件或触碰 IOKit 有重入风险。投递的 Escape 事件会显式清空 flagsevent?.flags []因为从.combinedSessionState构造的键盘事件会继承来源的修饰键——若不清空Escape 会以 ⌃⌥⇧⌘Escape 的形式发出去终端读取原始0x1B不受影响但聚焦的文本编辑器可能吞掉它见 docs/features/hotkeys.md。Caps Lock 的细节Caps Lock 作为 Hyper 键时是在硬件层面被重映射的。这是因为 Caps Lock 的切换包括指示灯和闩锁状态发生在所有 CGEventTap 之下没有任何 tap 能抑制它。Tinycast 使用 IOKitUserKeyMapping把 Caps Lock 重映射为F18与hidutil相同的机制见 HyperKeyTap.swift然后 tap 拦截 F18 顶替其位置。重映射在以下三种情况被移除你改选其他键作为 Hyper 键时Tinycast 退出时applicationWillTerminate会同步清除永远不会跨重启保留重启后 Caps Lock 恢复正常功能。由于重映射是异步的在它生效前的短暂窗口内按键仍以 Caps Lock 形式到达tap 会走修饰键路径兜底。这期间Caps Lock 指示灯仍可能闪动——那是未重映射的 HID 硬件行为不是 Tinycast 能阻止的。Hyper 键同样需要辅助功能权限且从不主动申请。Tinycast 会持续检查授权状态授权授予后立即开始工作授权被撤销时会立刻感知并停止每秒一次的看门狗会清理看似卡住的按键状态如丢失 release 事件的残留按下切换到其他用户时暂停工作切回后恢复——快速用户切换时另一个会话拥有键盘见 docs/features/hotkeys.md。隐藏、关闭与禁用快捷键到底归谁管文档明确区分了三层关闭语义容易混淆隐藏一行 ≠ 关闭其快捷键。取消某行复选框的勾选或在 launcher 中按⇧⌘H隐藏行只改变搜索结果已绑定的快捷键继续工作。这一点与 Commands 文档中Unticking one row only hides it from search; its shortcut keeps working一致。某个区块section的总开关会关闭其全部快捷键。以下四个开关会停止各自面板中的每一个快捷键Enable ApplicationsEnable System SettingsEnable System ActionsEnable Commands关闭某个功能会关闭它的快捷键。File Search、Notes、AI、Quick Actions、Navigation、Calendar、窗口命令、quicklinks、自定义命令和扩展都在执行任何操作前检查自身开关——例如 Search Files 与 Notes 会重新检查功能开关后才打开。重新打开功能后你的快捷键自动恢复工作。此外系统动作的确认对话框对快捷键同样生效重启、关机、注销、清空废纸篓、退出全部应用这五个动作通过快捷键触发时与在 palette 中触发一样弹出确认框无法绕过见 system-actions 的 Confirmation 一节。保留与持久化快捷键包含在备份中见 backup唯一例外是自定义 Quick Actions的快捷键。在你删除某个对象如 quicklink、自定义命令、窗口布局而 Tinycast 并未运行时对应的快捷键会在下次启动时被自动清理。这一清理prune在HotKeyManager.start()中完成见 HotKeyManager.swift对自定义命令、quicklink、窗口布局、自定义窗口尺寸、Quick Action 各自维护一个boundXxxIDs索引启动时用当前存活 ID 集合减去已存储集合清除那些对象已消失的绑定记录。Apple Shortcuts 的索引则特殊处理——不在启动时清理而在首次成功读取 Apple Shortcuts 库之后因为一次失败的读取看起来与删除完全一样见 docs/features/hotkeys.md。从源码看内部设计两种引擎一套绑定模型最后从架构层面总结这套系统的核心设计详见 docs/features/hotkeys.mdHotKeyBinding是动作唯一绑定的东西它有两个 case、对应两套引擎enum HotKeyBinding: Hashable, Sendable, Codable { case combo(KeyShortcut) // Carbon 注册处理组合键 case doubleTap(DoubleTapModifier) // DoubleTapMonitor 识别处理裸修饰键双击 }.combo走 CarbonRegisterEventHotKey见 HotKeyCenter.swift并带有可暂停能力——录制快捷键时全局暂停避免按键被吞.doubleTap由DoubleTapMonitor的只读事件 tap 识别因为 Carbon 完全无法看见单独的修饰键两者共享持久化、冲突检测、录制器与键帽渲染只有引擎不同。DoubleTapModifier的keycaps返回[glyph, glyph]即双击在 UI 上呈现为同一个修饰键符号出现两次见 DoubleTapModifier.swift。持久化格式绑定以 JSON 字符串保存在hotkey.action的 UserDefaults 键下HotKeyAction.defaultsKey是唯一计算键名的地方同时它也是HotKeyCenter的注册 ID——两者共享同一标识不可能漂移。例如剪贴板历史命令的绑定位于hotkey.command:clipboard-history。.combo序列化为{combo:{_0:{carbonKeyCode:N,carbonModifiers:N}}}.doubleTap序列化为{doubleTap:{_0:command}}。KeyShortcut保留了手写的init(from:)——这不是格式缝合而是保证每次解码都经过屏蔽设备修饰位的初始化器见 KeyShortcut.swift。同一漏斗原则命令的快捷键与其 launcher 行运行的是同一个执行通道——HotKeyAction.command(CommandID)对整个目录参数化并统一经由LauncherCoordinator.runCommand分发见 docs/features/hotkeys.md。因此一个命令只有一种行为而不是按调用途径各有一份实现新内置命令无需任何快捷键模块改动即可绑定。至此从录制一个快捷键到Hyper 键的硬件级重映射Tinycast 的全局快捷键体系已经完整呈现开箱零绑定、录制零权限、双击零成本未使用时、权限按需授权且永不强求。你可以直接参考 Hotkeys 参考文档 与 内部设计文档 继续深入或在 hotkey-test.swift 中查看完整的行为契约测试。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考