Qt macOS下如何正确设置系统黑体（如PingFang SC）作为应用默认字体？

Question

在 macOS 上使用 Qt 设置系统黑体（如 PingFang SC）作为全局默认字体时，常见问题为：调用 `QApplication::setFont()` 传入 `QFont("PingFang SC")` 后，部分控件（如 QComboBox 下拉列表、QMenu、QToolTip 或高 DPI 缩放场景下的 QLabel）仍显示为 Helvetica 或其他回退字体，而非预期的 PingFang SC。根本原因在于：Qt 在 macOS 平台对系统字体族名存在解析差异——`"PingFang SC"` 是显示名称而非底层 font family name；实际应使用 `"PingFang"`（无后缀），且需确保字体已安装并被 QFontDatabase 正确识别；此外，macOS 的 NSFont 系统级样式（如 Text Style）与 Qt 字体策略不完全对齐，导致 `QFont::defaultFamily()` 在不同 Qt 版本（尤其 Qt 5.15+ 与 Qt 6.x）中行为不一致。若未显式设置字号、字重或启用 `QFont::PreferQuality`，还可能触发字体回退至旧版 San Francisco 或 Helvetica。如何可靠获取并应用 macOS 原生推荐黑体，并适配暗色模式与动态字体缩放？

Answer 1

```html

一、现象层：典型复现场景与视觉异常表现

• 调用 QApplication::setFont(QFont("PingFang SC")) 后，主窗口 QLabel 显示正常，但 QComboBox 下拉项仍为 Helvetica
• QMenu 弹出时字体突然变细/变小，暗色模式下文字灰度不一致
• 在 macOS 14+ + Qt 6.7 高 DPI（200% 缩放）下，QToolTip 字体回退至 .AppleSystemUIFont（即 San Francisco Text），而非 PingFang
• 使用 QFontDatabase::families() 列出字体族，发现 "PingFang" 存在，但 "PingFang SC" 不在列表中

二、机制层：Qt/macOS 字体栈的三层解析偏差

Qt 在 macOS 上通过 Core Text → NSFont → UIFont 多层桥接，关键偏差点如下：

层级	Qt 行为	macOS 原生行为	偏差后果
字体族名解析	仅匹配 QFontDatabase::families() 返回的 family name（如 "PingFang"）	系统 UI 使用 NSFontTextStyleBody 等语义化样式，自动绑定 PingFang SC 或 SF Pro Display	硬编码字符串导致跨版本失效（如 macOS 15 可能默认启用 SF Pro）
字号适配	默认使用 pt 单位，未响应 [NSApp effectiveScreen].backingScaleFactor	NSFont 系统自动按逻辑点（point）→ 物理像素映射，并支持动态可访问性缩放（Accessibility Zoom）	高 DPI 下字体模糊或过小

三、验证层：精准探测系统推荐黑体的四步诊断法

1. 查可用族名：qDebug() << QFontDatabase::families(); —— 确认 "PingFang"、"SF Pro"、"Helvetica Neue" 是否存在
2. 查默认语义字体：通过 Objective-C++ 桥接调用 +[NSFont systemFontOfSize:0 weight:NSFontWeightRegular] 获取实际 family
3. 查当前模式：QGuiApplication::platformName() == "cocoa" 且 QGuiApplication::styleHints()->colorScheme() == Qt::ColorScheme::Dark
4. 查缩放因子：QGuiApplication::primaryScreen()->devicePixelRatio() 与 QApplication::font().pointSizeF() 联合判断是否需动态重设

四、解决方案层：生产级字体策略实现（Qt 6.5+ 推荐）

// macOS 原生黑体自适应初始化（含暗色/缩放/版本兼容）
void setupMacOSNativeFont(QApplication &app) {
    const auto osVersion = QOperatingSystemVersion::current();
    QString family;
    if (osVersion >= QOperatingSystemVersion::MacOSBigSur) {
        // Big Sur+ 优先 SF Pro；但若未安装（如部分企业镜像），fallback 到 PingFang
        if (QFontDatabase::supportsThreadedFontRendering() && 
            QFontDatabase::families().contains("SF Pro")) {
            family = "SF Pro";
        } else {
            family = "PingFang";
        }
    } else {
        family = "PingFang";
    }

    // 动态字号：基础 13pt，按系统缩放系数微调（避免整数截断）
    qreal basePt = 13.0;
    qreal scale = QGuiApplication::primaryScreen()->devicePixelRatio();
    int scaledPt = qRound(basePt * qMin(scale, 2.0)); // 封顶 2x

    QFont font(family, scaledPt);
    font.setStyleStrategy(QFont::PreferQuality | QFont::PreferOutline);
    font.setHintingPreference(QFont::HintingPreference::PreferFullHinting);

    // 暗色模式增强对比度（非简单换色，而是启用 SF Pro 的 Semibold variant）
    if (QGuiApplication::styleHints()->colorScheme() == Qt::ColorScheme::Dark) {
        font.setWeight(QFont::DemiBold);
    }

    app.setFont(font);

    // 关键：强制刷新所有已创建控件的字体（尤其 QMenu/QToolTip 这类延迟创建的 widget）
    QMetaObject::invokeMethod(&app, [&app]() {
        for (QWidget* w : QApplication::allWidgets()) {
            w->font() != app.font() ? w->setFont(app.font()) : void();
        }
    }, Qt::QueuedConnection);
}

五、架构层：面向演进的字体策略抽象（Mermaid 流程图）

graph TD A[启动应用] --> B{Qt 版本 ≥ 6.5?} B -->|Yes| C[调用 QGuiApplication::styleHints()->colorSchemeChanged] B -->|No| D[轮询 QGuiApplication::palette().colorGroup()] C --> E[监听系统暗色切换] D --> E E --> F[触发 fontRescaleEvent
含 DPI 变化 + scheme 变化] F --> G[执行 fontFamilyFallbackChain
SF Pro → PingFang → Helvetica Neue → systemDefault] G --> H[生成新 QFont 实例
带 PreferQuality & FullHinting] H --> I[广播 QEvent::FontChange 给所有 widget]

六、避坑层：五个被低估的硬约束

• ⚠️ 禁止在 QApplication 构造前调用 QFontDatabase::addApplicationFont() —— macOS Cocoa 初始化顺序敏感
• ⚠️ QToolTip 不继承 QApplication 全局字体，必须显式 QToolTip::setFont()
• ⚠️ QComboBox 下拉列表属于 QFrame 子窗口，需额外 qApp->setStyleSheet("QComboBox QAbstractItemView { font-family: \"PingFang\"; }")
• ⚠️ Qt 6.6+ 引入 FontConfig 支持，但 macOS 默认禁用，需编译时启用 -qt-fontconfig 并配置 FONTCONFIG_PATH
• ⚠️ San Francisco 和 PingFang 的字距（kerning）算法不同，长文本需测试 QFontMetrics::horizontalAdvance() 一致性

七、演进层：跨平台字体治理建议（2025 路线图）

建议在大型项目中引入字体策略中心（FontPolicyCenter），封装以下能力：

• 声明式字体描述 DSL（如 body: { family: native, weight: regular, scale: responsive }）
• 运行时字体健康检查（检测 family 是否缺失、是否触发 fallback、渲染质量评分）
• 与 Apple 的 UIFontMetrics 对齐的动态缩放 API（适配 VoiceOver 字体放大）
• 灰度模式（Grayscale Mode）下的 hinting 自动降级策略
• 支持 WebAssembly 目标时的字体回退链注入（如 SF → Inter → system-ui）

```