键盘亮度键调的是你正在用的那块屏幕,而不是永远只调 MacBook。
MacBook 接了外接显示器之后,按键盘上的亮度键(F1 / F2)通常只调 MacBook 自带屏。Apple 外接屏要去控制中心拖滑条,普通显示器往往还要按机身按钮。
FocusBright 在菜单栏里守着:按亮度键时,看当前焦点窗口在哪块屏上,就调哪块屏。
- 焦点在外接屏:FocusBright 接管,按 1/16 一格调亮度,Option+Shift 细调 1/64 一格,和系统一致
- 焦点在 MacBook 屏:原样交给系统,系统自带的亮度提示照常显示
- 单按 Option + 亮度键依旧打开「显示器」设置
根据设备自动选择硬件控制通道:Apple 屏使用 DisplayServices,第三方外接屏使用 DDC/CI 的 VCP 0x10(亮度)。
- ✅ MacBook 自带屏
- ✅ Apple Studio Display、Pro Display XDR 等 Apple 显示器
- 🧪 支持 DDC/CI 的第三方显示器(如 Dell USB-C 显示器):新增实验性支持,包含 Apple Silicon 和 Intel 通信路径
- 不支持 DDC/CI、没有有效回复或无法唯一匹配的设备:把按键原样交给系统
Apple 通道在 macOS 27 上实测通过。新增 DDC 通道已通过协议测试及 ARM / Intel 编译,尚待第三方显示器实机验证;不保证所有显示器、接口和扩展坞组合可用。
- 在显示器自身菜单中开启 DDC/CI(Dell 通常在「其他 / Others」里,具体以型号手册为准)。
- 优先 USB-C 或 DisplayPort 直连 Mac;部分扩展坞、KVM、HDMI 转接器和 DisplayLink 连接不透传 DDC。
- 在 FocusBright 菜单点「重新检测显示器」。检测成功后会出现亮度滑条,悬停可查看控制方式或失败原因。
- 如果仍无法调节,运行
--probe查看检测信息,并提供显示器具体型号、Mac 芯片和连接方式。该命令只检测、读取,不修改亮度。
插拔及唤醒后会自动重新检测。通信失败后停止接管该屏的亮度键;检查连接后可手动重新检测。不会用黑色遮罩模拟硬件亮度。
-
到 Releases 下载 dmg,打开后把 FocusBright 拖到「应用程序」。
-
首次打开会被 Gatekeeper 拦下(本地签名,未经 Apple 公证)。右键点击应用选「打开」,或在终端执行:
xattr -d com.apple.quarantine /Applications/FocusBright.app
-
首次启动会显示权限设置窗口。点击「打开辅助功能设置」,将窗口中的应用图标拖入权限列表,再打开 FocusBright 右侧开关。也可以点击「在 Finder 中显示」后,将应用拖入列表。授权后几秒内自动生效,不用重启。
要求 macOS 15 或更新。
打开后菜单栏出现太阳图标。之后照常按亮度键即可。
| 菜单项 | 说明 |
|---|---|
| 权限设置… | 随时查看授权与亮度键监听状态、打开系统设置或在 Finder 中显示应用 |
| 屏幕滑条 | 每块屏一个亮度滑条,标着「亮度键」的是现在按键会调的那块 |
| 重新检测显示器 | 重新识别硬件控制能力,适合开启 DDC/CI 或更换线缆后使用 |
| 亮度键调节 | 跟随焦点窗口所在屏幕(默认),或跟随鼠标所在屏幕 |
| 暂停接管亮度键 | 勾上后亮度键回到系统默认行为 |
| 开机启动 | 登录时自动运行 |
| 打开日志 | ~/Library/Logs/FocusBright/runtime.log,记录控制通道、检测结果及亮度读写情况 |
焦点窗口的位置用 CGWindowList 读取,只读窗口边框,不读标题和内容,所以不需要屏幕录制权限。
swift test # 跑测试
Scripts/build-app.sh && Scripts/make-dmg.sh # 本地打包到 build/
.build/debug/FocusBright --probe # 打印屏幕、亮度和当前焦点判断,排查问题用
# 已安装的应用也可以检测:
/Applications/FocusBright.app/Contents/MacOS/FocusBright --probeDDC 的读写和检测在串行后台队列进行,菜单和键盘事件只查询能力快照。只有校验通过的亮度回复才能启用 DDC,写入按设备返回的实际量程换算。多屏身份存在歧义时拒绝分配控制端点,避免调错屏幕。
本地签名每次重新构建都会变,旧的辅助功能授权可能失效。若列表里已开启却仍提示未授权,可在「权限设置…」中点击「修复旧授权…」并确认。此操作仅重置 FocusBright 的辅助功能授权;随后需重新添加当前应用并打开开关。修复仅在打包后的 FocusBright.app 内可用,命令行开发版本不提供重置。
发版:改 Resources/Info.plist 里的版本号并推到 main,然后在 GitHub 上用 v<版本号> 作 tag 发布 Release。
Actions 会自动测试、打 dmg、上传到这个 Release,并在说明末尾补上安装步骤。版本号以 tag 为准。
DDC 实现参考 MonitorControl,许可与署名见 THIRD_PARTY_NOTICES.md,打包时会一起包含在应用内。