Tinycast 系统动作指南31 个内置 macOS 快捷操作的完整实现与配置【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast导读System Actions系统动作是 Tinycast 面向 macOS 自身的一组内置操作——锁屏、睡眠、音量、蓝牙、废纸篓等共 31 个。本文以 website/content/docs/launcher/system-actions.md 文档为主体结合 SystemAction.swift、SystemActionRunner.swift 与 SystemActionCoordinator.swift 等源码展开完整覆盖全部动作清单、危险动作确认机制、执行反馈、音量 5% 网格、权限模型与设置面板帮助你理解并配置这套对 Mac 本身而非文件的操作体系。什么是系统动作系统动作是你对 Mac 做的操作而不是对某个文件做的操作。每一个动作都可以被搜索到并且每一个都可以绑定一个全局快捷键。在架构上它们拥有独立的体系启动器launcher/palette中有独立的System Actions分区。该分区的条目由 AppIndex.swift 以kind: .systemAction注册分区标题为System Actions设置中拥有独立的Settings → System Actions面板由 SystemActionsSettingsView.swift 承载对应 SettingsTab.swift 中名为System Actions的标签页。从源码结构看所有动作的唯一分发入口是 SystemActionCoordinator.swift 的runSystemAction(id:)方法它统一处理当前是否有调色板打开是否需要先隐藏调色板确认对话框以及结果反馈确保没有任何一条激活路径能够绕过安全关卡。完整动作清单31 个动作的清单在 SystemAction.swift 中通过SystemAction.ID枚举定义SystemActionCatalog.all 由ID.allCases生成测试 system-action-test.swift 断言目录恰好包含 31 个动作且覆盖每个 ID。按文档分组如下会话SessionLock Screen · Sleep · Sleep Displays · Restart · Shut Down · Log Out · Show Screen Saver媒体MediaPlay / Pause · Next Track · Previous Track音量VolumeToggle Mute · Turn Volume Up · Turn Volume Down · Set Volume… · Set Volume to 0% · 25% · 50% · 75% · 100%桌面DesktopShow Desktop · Toggle System Appearance · Toggle Stage Manager · Hide All Apps Except Frontmost · Unhide All Hidden Apps · Quit All Applications · Dismiss Notifications文件FilesOpen Trash · Empty Trash · Eject All Disks · Toggle Hidden Files硬件HardwareToggle Bluetooth每个动作在目录中都配有名称、SF Symbol 图标与持久化条目 ID格式为system-action:id见 SystemAction.swift。其中 Bluetooth 一项不使用 SF Symbol 而是内置资源源码注释明确指出该 Logo 是商标因此使用 bluetooth.imageset 中打包的图标SystemAction.swift。确认机制五个先问再做的动作有五个动作因为误操作代价高昂会先弹出确认对话框Restart · Shut Down · Log Out · Empty Trash · Quit All Applications交互约定为return执行esc取消每个对话框都显示该动作自己的图标让你一眼看清即将执行的操作Quit All Applications会提前统计要退出的应用数量并在确认文案中写明。在源码中确认行为由SystemAction.Confirmation枚举建模SystemAction.swiftrequired(title:message:)固定文案的确认用于 Restart、Shut Down、Log Out、Empty Trash 四个动作SystemAction.swiftcomputed确认文案在调用时动态计算专门用于 Quit All Applications——它会先通过 AppLauncher.quitAllTargets() 解析出真正要退出的应用列表再生成 Quit N applications? 的确认框SystemActionCoordinator.swift。测试 system-action-test.swift 精确断言只有这五个动作需要确认且required动作都带有非空的标题与正文Quit All 的确认类型是computed。两个关键安全特性值得注意快捷键同样触发确认——通过全局快捷键触发时同一个问题照样会出现没有任何绕过途径长按快捷键不会叠加对话框——即使一直按住快捷键也只会出现一个确认框不会堆积多个。执行后的反馈对于没有可见效果的动作Tinycast 会明确告诉你结果落在哪里例如Trash Emptied、Hidden Files Shown、Dark Appearance、Bluetooth Off、3 Disks Ejected。反馈的两种状态SystemActionRunner.swift绿色对勾.success语气表示状态发生了改变普通圆点.neutral语气表示无事可做是信息而非失败。因此Trash Is Already Empty是一个回答而不是错误。Eject All Disks、Dismiss Notifications、Unhide All Hidden Apps 返回的同类无事可做消息同理。这一语义由SystemActionFeedback.isNoOp建模协调器在展示时据此切换语气SystemActionCoordinator.swift底层展示走 AppCore.showMessage 的瞬时消息胶囊。一些值得注意的细节音量5% 网格与自绘 HUDTurn Volume Up / Down沿5% 网格移动从 37% 开始向上到 40%向下到 35%。实现位于 VolumeLevel.swift网格为 20 个 5% 步进steps 20、step 0.05stepped(_:up:)把当前值吸附到前进方向上的最近网格线且不会越过它VolumeLevel.swift。网格内的一个1e-6容差用于吸收浮点误差避免向下步进时原地不动。volume-test.swift 对这套逻辑做了完整验证37% 向上落到 40%、向下落到 35%volume-test.swift1% 向下落到 0%99% 向上落到 100%2.1% 这种刚过 2%的毛刺值仍会向上进到 5%volume-test.swift从 37% 连续向上按 40%→45%→50%→55% 爬升、向下按 35%→30%→25%→20% 回落一旦落到网格线就保持圆整volume-test.swift0% / 25% / 50% / 75% / 100% 五个预设恰好落在网格线上所以预设之后的步进依然是圆整值volume-test.swift。Tinycast 会显示自己的音量 HUD因为 macOS 只为真实媒体键显示系统音量条。该 HUD 的行为以数字显示当前音量级别静音时显示Muted而非0%显示 1.6 秒后淡出。1.6 秒这个驻留时长定义在 Theme.swift 的Theme.Duration.volumeHUDHUD 的显示/替换/驻留/淡出由 HUDPresenter 统一管理重复操作会延长驻留而不是重放动画HUDPresenter.swift。HUD 定位在鼠标所在屏幕、距底部 12% 高度处VolumeHUDController.swift。Set Volume…是一个交互式动作协调器先读取当前音量弹出带滑杆的 Set Volume 对话框由 DialogController.pickVolume 提供用户确认后写入所选值。底层的音量读写通过 CoreAudio 的AudioObjectGetPropertyData/AudioObjectSetPropertyData完成SystemActionRunner.swift优先操作 master 音量元素否则回退到立体声首选声道并取平均值若当前输出设备不支持软件音量会抛出明确错误。静音Toggle Mute也做了健壮性处理若设备没有 mute 控件则把音量归零并在恢复时还原上一个非零值SystemActionRunner.swift。Eject All Disks 的磁盘判定Eject All Disks弹出外部和可移动磁盘包括扩展坞dock上的硬盘但永远不会触碰内部卷或网络卷。其判定逻辑在 SystemActionRunner.swift通过FileManager.mountedVolumeURLs枚举已挂载卷过滤条件必须是非内部、非根文件系统、非网络volumeIsLocal且满足可弹出volumeIsEjectable或非内部volumeIsInternal false——注释说明扩展坞上的固定介质硬盘不是 ejectable 的所以外部本身也够格弹出采用NSWorkspace.unmountAndEjectDevice(at:)单个卷的弹出可能顺带带走同一设备上的其他卷因此每个卷在操作前都会重新确认是否仍处于挂载状态全部弹出后返回计数0 个返回 No Disks to Ejectno-op1 个返回 1 Disk Ejected多个返回 N Disks Ejected有失败项时汇总抛出 Some disks could not be ejected。前台应用感知的两个动作Hide All Apps Except Frontmost和Quit All Applications在通过快捷键调色板关闭状态触发时作用于真正位于最前方的应用。协调器在触发前会通过paletteCoordinator.targetApp取得前台应用并传给执行器SystemActionCoordinator.swift隐藏其他应用时保留它并把它重新激活SystemActionRunner.swift。Quit All 的行为细节Finder 和 Tinycast 本身不会被退出quitAllExclusions排除com.apple.finder因为terminate()只会让 Finder 重新启动并且通过 PID而非激活策略排除 Tinycast 自身AppLauncher.swift礼貌退出应用通过terminate()收到标准退出请求因此有未保存工作的应用仍会弹出保存询问。Toggle System Appearance 作用于 macOS 本身Toggle System Appearance改变的是macOS 本身而不只是 Tinycast。实现上通过 AppleScript 切换 System Events 的暗色模式并返回结果状态SystemActionRunner.swift反馈文案相应显示Dark Appearance或Light Appearance。Tinycast 自身只有在主题设置为System时才跟随系统外观变化。该选项位于Settings → General → Appearance的 Theme 栏website/content/docs/palette.md默认值即 System源码层面 AppAppearance.swift 中.system返回nilNSAppearance把外观选择交还给 AppKit 跟随 macOS 实时变化。其余动作的实现路径从 SystemActionRunner.swift 可以完整看到各动作的底层实现值得了解的关键路径Lock Screen合成⌃⌘Q键盘事件需要辅助功能权限Sleep / Sleep Displays调用/usr/bin/pmset sleepnow/displaysleepnowRestart / Shut Down / Log Out通过 AppleScript 操作 System EventsShow Screen Saver打开/System/Library/CoreServices/ScreenSaverEngine.appPlay / Pause · Next Track · Previous Track向系统事件队列投递与真实媒体键相同的 16/17/18 号媒体键事件0xA/0xB为按下/抬起状态Show Desktop调用 Mission Control 二进制并传参1Toggle Stage Managerdefaults write com.apple.WindowManager GloballyEnabled -bool且写入后会回读校验toggleDefault通用流程见 SystemActionRunner.swiftToggle Hidden Filesdefaults write com.apple.finder AppleShowAllFiles后killall Finder并容忍退出码 0/1Open Trash直接打开~/.TrashFinder 打开失败时报错Empty Trash先用 AppleScript 让 Finder 统计废纸篓条目数——注释说明 Finder 对空废纸篓会报错且~/.Trash受 TCC 保护所以先计数为 0 直接返回 Trash Is Already Empty否则执行empty trash并返回 Trash EmptiedSystemActionRunner.swiftUnhide All Hidden Apps遍历runningApplications中所有isHidden的应用逐个unhide()Dismiss Notifications通过辅助功能 API 在 Notification Center 的 AX 树中查找可点击的关闭控件——按AX subrole匹配不依赖界面语言只点击 close/dismiss/clear-all 控件而非任意按钮每处理一条等待 150ms并设有 100 条的安全上限SystemActionRunner.swiftToggle Bluetoothdlopen加载 IOBluetooth 框架通过IOBluetoothPreferenceGet/SetControllerPowerState切换并轮询确认最终状态SystemActionRunner.swift。权限模型部分动作需要自动化Automation、辅助功能Accessibility或蓝牙Bluetooth权限。关键原则按需请求绝不提前只有在你第一次运行需要该权限的动作时才请求不会一上来就要全部权限拒绝后的引导如果你拒绝不会无声无息——你会看到一条带有指向正确系统设置面板链接的消息而不是什么都不发生。实现上SystemActionFailure携带Settings枚举.accessibility/.automation/.bluetooth见 SystemActionRunner.swift协调器收到后展示失败对话框并提供 Open System Settings… 恢复按钮点击后通过x-apple.systempreferences:com.apple.preference.security?Privacy_*URL 直接跳转到对应隐私面板SystemActionCoordinator.swift。各权限对应的失败文案也各不相同例如辅助功能缺失时提示 Allow Tinycast to control your Mac in Accessibility settings自动化缺失AppleScript 错误码-1743时提示到 Automation 面板SystemActionRunner.swift。设置面板Settings → System Actions面板SystemActionsSettingsView.swift复用通用的 LauncherItemsSection其结构为顶部是Enable System Actions总开关下面每个动作一行每行包含启动器勾选框、快捷键录制器和别名alias字段顶部有一个筛选字段便于在 31 行中快速定位。该面板同时对应 SettingsSearchCatalog.swift 中的 Enable System Actions 搜索锚点。两个层级的可见性控制LauncherItemsSection.swiftEnable System Actions 关闭把所有动作移出搜索并关闭它们的快捷键——即整类禁用单个行的勾选框只把该动作从搜索中隐藏不影响快捷键启动器中按⇧⌘H的效果与此相同。从源码结构看可见性状态由VisibilityStore统一管理isKindEnabled控制整类开关isItemVisible控制单条条目快捷键与别名分别由HotKeyManager、AliasStore提供LauncherItemsSection.swift。小结系统动作模块体现了 Tinycast对 Mac 本身的操作这一功能面的完整设计31 个动作以SystemAction.ID枚举单一来源定义并经受测试校验危险动作强制确认且快捷键也无法绕过执行结果通过绿色对勾/中性圆点区分变化与无事可做音量操作建立在 5% 网格与自绘 HUD 之上权限按需请求并在失败时引导到准确的系统设置面板。无论是想要了解每个动作的实现原理还是想为常用系统操作配置快捷键本文覆盖的清单、行为与源码路径都可以作为直接的参考起点。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考