Qt 与 AWTK 对比踩坑

将项目从技术栈AWTK切换到QT的过程中，由于对框架不了解，踩了一些坑，特此记录。

不要过度在 Designer 上嵌套 Box Layout

• 不要为了自适应把 .ui 做成连续嵌套的 Box layout，例如 layout1 -> layout2 -> layout3。

• 原因：Qt Designer 在 layout 里面复制粘贴和插入新控件很不顺手，连续嵌套后既要维护 layout 层级，又要维护控件本身，复杂页面的调整成本会非常高。

• 解决方法： 多级layout之间间隔留出无layout区交给代码调整，避免连续嵌套，比如layout1和3嵌套，layout2就不嵌套； QScrollArea 内容区、数据驱动列表等场景通常适合用 QVBoxLayout，页面级相对位置和屏幕自适应（如保持离右 20px、离底 10px、随窗口同步可用区域）可交给代码处理； 控件基础尺寸、层级和可视结构仍尽量保留在 Designer 中，代码只维护 Designer layout 难以表达或维护的动态关系；

按键菜单单选控件不要使用 QRadioButton

• 不要在需要按键控制的菜单单选场景中使用 QRadioButton。

• 原因：Qt QRadioButton 与 AWTK radio_button 的焦点和选中行为不同。启用 autoExclusive 后，Qt 会调整组内按钮的焦点策略，使焦点难以正常移出 group；使用方向键移动焦点时，原生逻辑还会自动选中获得焦点的按钮，从而同步修改 value。

• 解决方法：使用 QCheckBox 承载单选按钮外观，关闭 Qt 原生 autoExclusive，在点击、Space 或 Enter 激活时通过 setChecked() 手动保证组内唯一选中；也可以将该行为封装为项目自定义控件。

复杂按钮背景图和状态图标不要使用 QSS

• 当按钮选中状态需要将图片平铺或拉伸到整个背景，或者需要把 icon 绘制到特定区域时，例如给某个按钮做一个右上角打✔️的效果，不要使用 QSS 实现。

• 原因：QSS 的 background-image 和 border-image 都难以精确复刻 AWTK 对背景图、icon 的平铺、拉伸、对齐和区域定位能力；Qt Designer 也没有 AWTK 针对背景图和 icon 提供的完整配置。QSS 尤其难以在同一状态下稳定实现背景图与独立 icon 的叠加绘制。

• 解决方法：封装自定义控件，在 paintEvent() 中使用 QPainter 画布 API，通过 drawPixmap()、drawIcon() 等接口分别控制背景、状态图标、裁剪区域与绘制顺序。

Qt 没法像 AWTK 那样让子控件越界绘制

• AWTK 通常将控件统一绘制到同一张 canvas，可以通过取消 clip 让子控件画到容器外；Qt Widgets 使用父子控件树，子 QWidget 的绘制区域始终受父控件限制。

避免频繁调用 setStyleSheet

• 不要在页面每次 showEvent() 或普通状态刷新时无条件重新 setStyleSheet()，尤其不要在大菜单页根控件上反复应用整页 QSS。

• 原因：AWTK 更接近统一 canvas 绘制，改颜色通常只是影响后续绘制参数；Qt Widgets 的 setStyleSheet() 会进入样式表解析、选择器匹配和控件 repolish 流程。即使新旧 QSS 字符串完全相同，Qt 也不会自动去重。控件已 polish 后再次调用 setStyleSheet()，会对目标控件及其子孙控件重新匹配规则。QWidget#Page *、QWidget、* 等宽泛后代选择器会进一步放大成本。

• 解决方法：

  • 对仍需 QSS 的页面/组件，在 loadStyleSheet(int theme) 内记录已应用主题，主题未变化时直接返回；不要把守卫一概放到 onSwitchTheme()，避免跳过非 QSS 的状态同步。

  • 纯色背景、圆角行背景、简单文本颜色等优先用 paintEvent() 自绘，主题变化只更新颜色并 update()。

  • 复杂视觉必须保留 QSS 时，使用 objectName、具体控件类型或自定义属性精确匹配，避免 QWidget#Page * 这类通配后代选择器。

  • 不要指望 QPalette 一定能替代 QSS；在父级样式表或自定义绘制链路下，文本颜色可能被覆盖。若要彻底绕开样式表机制，文本也应由控件自绘。