丁香医生1. 项目概述：为什么要自定义标题栏？
在开发桌面应用时，默认的窗口标题栏往往显得千篇一律。PyQt6作为Python生态中最成熟的GUI框架之一，虽然提供了完整的窗口管理系统，但原生标题栏的样式调整空间非常有限。最近在开发一个音乐播放器项目时，我发现系统默认的标题栏与设计的深色主题严重不协调，于是决定深入研究PyQt6的标题栏自定义方案。
传统方案是直接隐藏系统标题栏（setWindowFlag(Qt.FramelessWindowHint)），但这会丧失窗口拖拽、双击最大化等关键交互功能。经过多次实践，我总结出一套既能保留完整窗口功能，又能实现视觉自定义的完整方案。下面分享从原理到实现的完整过程。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术方案选型与原理分析
2.1 原生标题栏的局限性
PyQt6的QMainWindow默认使用操作系统提供的原生标题栏，这带来三个主要限制：
- 样式不可控：无法修改背景色、按钮形状等视觉元素
- 布局固定：无法在标题栏区域添加自定义控件
- 功能耦合：关闭/最小化等按钮行为与系统强绑定
2.2 主流解决方案对比
| 方案 | 优点 | 缺点 |
|---|---|---|
| 完全隐藏标题栏 | 完全自定义UI | 丧失所有窗口管理功能 |
| 系统API Hook | 保留原生功能 | 平台依赖性强，实现复杂 |
| 模拟标题栏(本文方案) | 功能完整，跨平台一致 | 需要手动实现拖拽逻辑 |
2.3 关键技术原理
核心思路是通过组合两种QWidget特性：
- 窗口标记控制：使用
setWindowFlags()保留窗口边框但隐藏标题栏 - 事件过滤器：重写鼠标事件实现拖拽逻辑
- QSS样式表：完全控制窗口部件的视觉表现
关键代码片段：
python复制# 保留窗口边框但隐藏标题栏
self.setWindowFlags(Qt.Window | Qt.CustomizeWindowHint)
3. 完整实现步骤
3.1 基础窗口设置
首先创建继承自QMainWindow的自定义窗口类：
python复制from PyQt6.QtWidgets import QMainWindow, QPushButton
from PyQt6.QtCore import Qt
class CustomTitleBarWindow(QMainWindow):
def __init__(self):
super().__init__()
# 关键设置：保留窗口属性但隐藏默认标题栏
self.setWindowFlags(Qt.WindowType.Window |
Qt.WindowType.CustomizeWindowHint)
# 必须设置窗口背景否则透明
self.setAttribute