Skip to content

About

macOS 状态栏显示器控制工具,支持屏幕开关、HDR、分辨率、刷新率、HiDPI 和 ColorSync 配置。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

24 Commits

Folders and files

Repository files navigation

DisplayBar

English README

DisplayBar 是一个 macOS 状态栏显示器控制工具,用来快速管理外接屏幕。 它基于 displayplacer,并额外打包了几个本地 helper,用来处理 displayplacer 本身没有直接暴露的能力,例如 HDR 和 ColorSync 颜色配置。

DisplayBar 状态栏控制面板

下载

最新可用版本在 GitHub Releases:

下载 DisplayBar-0.1.0.dmg

打开 DMG 后,把 DisplayBar.app 拖到 Applications 即可。

当前 App 使用 ad-hoc 签名,已经避免 App bundle 签名结构损坏,但还没有使用 Apple Developer ID 签名和 notarize。首次打开时 macOS 仍可能会拦截。如果你信任这个开源项目, 可以在“系统设置 > 隐私与安全性”里允许打开,或右键 App 选择“打开”。通常不需要执行命令; 如果被下载工具额外加了隔离属性,才可能需要手动移除 quarantine。

适合谁

  • 经常在 macOS 上切换多屏配置的人。
  • 外接屏需要频繁调整分辨率、刷新率、HiDPI 或 HDR 的人。
  • 希望像 Windows 一样快速切换扩展、复制、仅主屏、仅副屏的人。
  • 需要快速切换 ColorSync 颜色配置的外接屏用户。

这个工具主要面向个人多屏场景:快速开启或关闭某个屏幕、切换分辨率和刷新率、 开启或关闭 HiDPI/HDR、设置主屏幕、切换 ColorSync 颜色配置,以及在需要手动调整时 直接跳转到 macOS 的显示器排列设置。

功能

  • 状态栏 popover 界面,修改设置时不会因为点击控件就自动关闭。
  • 菜单栏固定显示 DB 入口,避免后台运行但入口不可见。
  • 支持开机启动。
  • 展示当前在线屏幕。
  • 内置屏幕会参与显示和模式配置,但不提供关闭/救援开启控制。
  • 通过 displayplacer 开启或关闭屏幕。
  • 对被关闭或离线的历史屏幕提供恢复入口。
  • 对消失的屏幕提供 patched displayplacer 救援路径。
  • 设置显示模式:
    • 分辨率
    • 刷新率
    • HiDPI 缩放
    • 基于 connection mode 的颜色位数
  • 读取并调节 macOS 暴露的软件亮度。
  • 通过 macOS 私有显示 API 按屏幕开启或关闭 HDR。
  • 设置主屏幕。
  • 切换屏幕模式:
    • 扩展
    • 复制
    • 仅主屏
    • 仅副屏
  • 设置简单的副屏排列:
    • 副屏在左
    • 副屏在右
    • 副屏在上
    • 副屏在下
  • 直接打开 macOS 显示器系统设置,用于系统级屏幕排列。
  • 读取并设置每个屏幕的 ColorSync 颜色配置。

系统要求

  • macOS。
  • 支持外接屏幕的 Apple Silicon 或 Intel Mac。
  • 构建时需要 Xcode Command Line Tools。

下载版会优先使用 App 内置的 displayplacer。源码运行时会按顺序查找: DISPLAYPLACER、App Resources、/opt/homebrew/bin/displayplacer、/usr/local/bin/displayplacer。 如果你想指定自己的 displayplacer,可以设置环境变量:

DISPLAYPLACER=/path/to/displayplacer

构建

在仓库根目录运行:

./statusbar-tool/build.sh

生成的 App 在:

statusbar-tool/build/DisplayBar.app

构建脚本会同时编译:

  • Swift 状态栏 App
  • hdrctl
  • profilectl
  • 打包到 App Resources 内的 helper

自行打包 DMG

从源码生成可下载、可拖入 Applications 的 DMG:

./scripts/package-dmg.sh

输出文件:

dist/DisplayBar-0.1.0.dmg

运行

从仓库直接运行:

./statusbar-tool/run.sh

或打开构建后的 App:

open statusbar-tool/build/DisplayBar.app

当在线屏幕多于一个时,状态栏图标会显示当前在线屏幕数量。

环境变量

可选配置:

DISPLAYPLACER=/path/to/displayplacer
DISPLAY_CONTROL_TOOL_HOME=/path/to/display-control-tool

Helper 用法

HDR:

./statusbar-tool/build/hdrctl status 1 3
./statusbar-tool/build/hdrctl on 1
./statusbar-tool/build/hdrctl off 1

ColorSync 颜色配置:

./statusbar-tool/build/profilectl list 1 3
./statusbar-tool/build/profilectl set 1 1 /Library/ColorSync/Profiles/Displays/example.icc
./statusbar-tool/build/profilectl reset 1 1

patched 屏幕恢复脚本:

./scripts/wake-displays-patched.sh

关闭屏幕与恢复

通过 displayplacer 关闭屏幕后,这个屏幕可能会从 displayplacer list 里消失。 这种情况下,普通 displayplacer 可能无法再操作这个丢失的 id。

DisplayBar 会记录曾经见过的屏幕,并在单独区域显示已关闭或离线屏幕。对于关闭后消失的屏幕, DisplayBar 可以使用 bin/displayplacer-patched 作为救援路径。

真正关闭显示器属于偏高级的操作。只想临时不用某个屏幕时,黑屏遮罩通常比真实关闭显示器更安全, 因为真实关闭可能影响排列、主副屏和窗口位置。

HDR 说明

displayplacer 不提供 HDR 控制。DisplayBar 使用 macOS 私有显示 API:

  • CoreDisplay_Display_SupportsHDRMode
  • CoreDisplay_Display_IsHDRModeEnabled
  • CoreDisplay_Display_SetHDRModeEnabled
  • SLSDisplaySupportsHDRMode
  • SLSDisplayIsHDRModeEnabled
  • SLSDisplaySetHDRModeEnabled

这些 API 可能随 macOS 版本变化。DisplayBar 在切换 HDR 后会再次读取状态; 如果 macOS 读回来的状态符合请求,就认为操作成功。

颜色配置

颜色配置通过 profilectl 使用公开 ColorSync API。

DisplayBar 会优先读取与当前屏幕绑定的 ColorSync profile,并把当前 profile 放在下拉列表最前面。 当 ColorSync 在远程桌面或离线屏幕状态下无法返回完整设备表时,DisplayBar 会回退到系统中可用的 显示器 ICC/ICM 文件列表。

一些显示器 profile 的 ICC 内部描述可能是通用名称,例如“普通灰度描述文件”。对于 /Library/ColorSync/Profiles/Displays/*.icc 这类显示器专用文件,DisplayBar 会优先使用文件名里的 显示器名称,例如 Odyssey G5-UUID.icc 会显示为 Odyssey G5。

10-bit 颜色位数

DisplayBar 会同时显示图形位深和链路位深。图形位深来自 macOS 当前图形模式, 链路位深来自 WindowServer 的 LinkDescription.BitDepth。

Apple Silicon 上 displayplacer list 可能只列出 color_depth:8,但底层链路仍然可以是 10-bit。DisplayBar 的颜色位数下拉会写入 connection mode 对应的链路位深,而不是只发送 displayplacer color_depth:10。

只有 macOS 读回链路位深为 10-bit 时,才应该认为 10-bit 链路真正生效。如果读回仍是 8-bit,说明当前 macOS、线缆、刷新率、HDR 或屏幕组合没有接受 10-bit 请求。

远程桌面注意事项

ToDesk、Moonlight 等远程桌面工具可能影响 macOS 的显示器枚举和 ColorSync 设备表:

  • 离线屏幕可能无法完整读取。
  • ColorSync 可能只返回当前屏幕的一条 profile。
  • 分辨率、刷新率、HDR 或颜色位数列表可能和本机直连时不同。

如果颜色配置或屏幕列表看起来异常,建议在本机屏幕前直接操作一次,或打开 macOS 系统设置确认。

仓库结构

.
├── bin/
│   └── displayplacer-patched
├── patches/
│   ├── README.md
│   └── changes.diff.txt
├── scripts/
│   ├── check-displays.sh
│   ├── main-only-dangerous.sh
│   ├── package-dmg.sh
│   ├── restore-dual.sh
│   └── wake-displays-patched.sh
└── statusbar-tool/
    ├── Sources/DisplayBar/main.swift
    ├── build.sh
    ├── hdrctl.c
    ├── profilectl.c
    └── run.sh

本地显示器脚本配置

scripts/restore-dual.sh 和 scripts/main-only-dangerous.sh 使用环境变量读取显示器 ID,不包含个人设备 UUID。先运行 displayplacer list,再设置本机变量:

export PRIMARY_DISPLAY_ID='<primary-display-id>'
export SECONDARY_DISPLAY_ID='<secondary-display-id>'
./scripts/restore-dual.sh

默认模式是 1920×1080、60 Hz、双屏横向排列。可使用 PRIMARY_DISPLAY_MODE 和 SECONDARY_DISPLAY_MODE 覆盖完整模式参数;请根据自己的屏幕调整。未配置所需 ID 时脚本会退出,不执行显示器变更。

已知限制

  • 当前项目主要用于个人 macOS 多屏实验,App 使用 ad-hoc 签名,但还不是 Developer ID 签名和 notarize 的完整分发软件。
  • HDR 使用私有 API,未来 macOS 版本可能失效。
  • 屏幕开启、关闭和恢复行为依赖 macOS、屏幕固件、线缆、扩展坞和 displayplacer。
  • 10-bit 是否生效必须以 macOS 读回值为准。
  • patched rescue binary 只是针对“关闭后屏幕消失”的 workaround,不是上游 displayplacer 的通用替代品。

当前构建警告

构建时可能出现两个非致命 warning:

  • NSBox.borderType 已被 macOS 标记为 deprecated。
  • rebuildMenu() 中保留了一段早期 NSMenu 代码,当前 popover 路径会提前 return。

这两个 warning 不影响当前 App 运行。

About

macOS 状态栏显示器控制工具,支持屏幕开关、HDR、分辨率、刷新率、HiDPI 和 ColorSync 配置。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages