1. 课程导入
在桌面端与嵌入式 Qt Quick 项目中，界面能否在 1080p 显示器、4K 屏幕、笔记本内屏与外接投影仪之间保持一致、清晰、可交互，已经成为衡量交付质量的重要标准。很多开发者第一次遇到“同一份 QML 在 4K 屏上按钮变得极小”“窗口拖到副屏后字体模糊”“高 DPI 下鼠标点击位置偏移”等问题时，往往误以为是控件写错了，实际上根源在于对 Qt 的屏幕模型、设备像素比、逻辑坐标与物理像素之间的关系缺乏系统认识。本课程的目标，就是把这套看似零散的适配知识整理成一条可落地的工程路线。
一、学习目标：从“能显示”到“显示得对”
完成本课程后，你应当具备以下能力：第一，理解 QScreen、QGuiApplication、QWindow 与 QQuickWindow 在多屏环境中的职责边界，能够枚举屏幕、监听屏幕增删与几何变化；第二，掌握 devicePixelRatio、逻辑像素、物理像素、缩放因子之间的换算关系，能解释为什么 100×100 的逻辑矩形在 200% 缩放下会占用 200×200 的物理像素；第三，能够使用 Qt 提供的 High DPI 策略与属性，在启动阶段正确配置缩放行为；第四，能够针对多屏不同 DPI 的场景，设计可动态迁移、可重排布局的 QML 界面；第五，能够定位并修复模糊、错位、截断、性能下降等典型适配缺陷。
二、核心挑战：多屏与高分辨率到底难在哪里
多屏适配的复杂性来自“环境不确定”和“坐标不唯一”两个事实。环境不确定，指用户可能热插拔显示器、旋转屏幕、修改系统缩放、把窗口从主屏拖到副屏；坐标不唯一，指同一个界面元素在逻辑坐标系、窗口坐标系、屏幕坐标系和物理像素坐标系中拥有不同数值。若代码只按单一坐标系编写，就会在环境变化时暴露问题。
- 缩放不一致：主屏 100%、副屏 150%，窗口跨屏时若未重新计算，控件尺寸与命中区域会失配。
- 像素密度差异：4K 屏上 1 逻辑像素对应多个物理像素，位图资源若未提供高分辨率版本会发虚。
- 窗口迁移：窗口从一个屏幕移动到另一个屏幕时，devicePixelRatio 可能变化，需要触发重新布局与资源切换。
- 性能压力：高分辨率下渲染面积成倍增长，过度绘制、阴影、模糊特效会显著拉低帧率。
- 平台差异：Windows、macOS、Linux 与嵌入式平台对 High DPI 的默认策略和可用 API 并不完全一致。
下面这张图把本节涉及的核心对象、坐标层级与适配决策点组织成一张关系图，帮助你在进入后续章节前建立整体心智模型。
三、整体知识框架：四个层次、一条数据流
本课程把适配知识划分为四个层次。第一层是应用与屏幕层，关注 QGuiApplication 的 High DPI 属性、QScreen 的枚举与信号、屏幕几何与可用区域；第二层是窗口与坐标层，关注 QQuickWindow 的坐标转换、窗口跨屏迁移、devicePixelRatio 的读取与响应；第三层是QML 布局与资源层，关注逻辑像素布局、锚定与布局管理器、矢量图与多倍图、字体与图标缩放；第四层是渲染与性能层，关注渲染目标尺寸、过度绘制、特效开销与帧率稳定性。四层之间通过“屏幕信息 → 窗口参数 → 布局决策 → 渲染输出”这条数据流串联。
| 层次 | 核心对象 | 关键参数 | 典型问题 |
|---|---|---|---|
| 应用与屏幕层 | QGuiApplication、QScreen | HighDpiScaleFactorRoundingPolicy、devicePixelRatio | 缩放策略不一致、屏幕枚举遗漏 |
| 窗口与坐标层 | QQuickWindow、QWindow | geometry、screen、devicePixelRatio | 跨屏后坐标错位、窗口尺寸跳变 |
| QML 布局与资源层 | Item、Layout、Image、Font | width/height、sourceSize、pixelSize | 位图模糊、文字截断、间距失衡 |
| 渲染与性能层 | SceneGraph、RenderTarget | renderTargetSize、frameRate | 高分辨率掉帧、显存占用过高 |
四、实战路线图：从启动配置到多屏验证
为了让知识真正落地，本课程给出一条可执行的实战路线。第一步，在 main 函数中显式设置 High DPI 相关属性，避免依赖平台默认值；第二步，封装一个屏幕信息工具类，统一读取当前屏幕的 DPR、逻辑 DPI 与可用区域；第三步，在 QML 根窗口监听 screenChanged，触发布局重算与资源切换；第四步，使用矢量图或按 DPR 提供多倍图，避免位图拉伸；第五步，建立多屏测试矩阵，覆盖 100%、150%、200% 缩放与跨屏拖拽场景。
// main.cpp 启动阶段的关键配置示例
QGuiApplication::setHighDpiScaleFactorRoundingPolicy(
Qt::HighDpiScaleFactorRoundingPolicy::PassThrough);
QGuiApplication app(argc, argv);
// 在 QML 中可通过 Screen 附加属性读取当前屏幕信息
// Screen.devicePixelRatio、Screen.width、Screen.height
五、常见误区与复盘
第一个误区是“把逻辑像素当物理像素用”，在 QML 中直接按物理分辨率写死尺寸，导致高 DPI 下界面过大或过小。第二个误区是“只在启动时读取一次 DPR”，忽略窗口跨屏后 DPR 变化，造成布局不更新。第三个误区是“用位图代替矢量图”，在高分屏上放大后边缘模糊。第四个误区是“为了清晰无限提高渲染倍率”，结果帧率骤降、显存暴涨。复盘时应回到数据流：屏幕信息是否实时、窗口参数是否响应、布局是否基于逻辑像素、资源是否按 DPR 选择、渲染是否在可接受开销内。