PyQt-Frameless-Window 自定义标题栏完全指南：从 TitleBar 到 StandardTitleBar

PyQt-Frameless-Window 自定义标题栏完全指南从 TitleBar 到 StandardTitleBar【免费下载链接】PyQt-Frameless-WindowA cross-platform frameless window based on PyQt/PySide, support Win32, Linux and macOS.项目地址: https://gitcode.com/gh_mirrors/py/PyQt-Frameless-Window想要用 PyQt5 做出像 Spotify、VS Code 那样干净漂亮的无边框窗口却总被系统默认标题栏拖后腿PyQt-Frameless-Window就是为这个痛点而生的跨平台开源库它基于 PyQt/PySide完整支持 Win32、Linux 和 macOS自带了移动窗口、边缘拉伸、窗口阴影、窗口动画以及 Win11 Snap Layout、Win10/11 亚克力与 Mica 模糊等高级能力。而这一切体验的核心正是它的自定义标题栏体系。本文将带你从默认的TitleBar一路走到StandardTitleBar学会如何打造属于自己的个性化标题栏。什么是 PyQt-Frameless-Window快速认识这个跨平台无边框窗口库PyQt-Frameless-Window 是一个专门解决无边框窗口痛点的 Python 库。普通窗口去掉系统边框后会立刻失去拖拽移动、缩放、阴影等基础能力体验很差。这个库通过 Win32 API、X11 和 macOS 原生接口的封装帮你把这些能力全部找回来️窗口移动按住标题栏任意拖动边缘拉伸5 像素宽的热区缩放Windows 平台️窗口阴影与动画原生级视觉反馈Win11 Snap Layout悬停最大化按钮即可分屏亚克力 / Mica / Aero 模糊按系统版本自动适配安装非常简单一条 pip 命令即可搞定pip install PyQt5-Frameless-Window3 分钟上手第一个无边框窗口的极简写法使用这个库你只需要继承FramelessWindow或FramelessMainWindow项目核心入口定义在 qframelesswindow/init.py 中会根据当前操作系统自动选择对应的窗口实现import sys from PyQt5.QtWidgets import QApplication from qframelesswindow import FramelessWindow class Window(FramelessWindow): def __init__(self, parentNone): super().__init__(parentparent) self.setWindowTitle(PyQt-Frameless-Window) self.titleBar.raise_() # 别忘了把标题栏置顶 if __name__ __main__: app QApplication(sys.argv) demo Window() demo.show() sys.exit(app.exec_())注意self.titleBar.raise_()这一行它确保自定义标题栏始终显示在所有内容之上是新手最容易漏掉的关键一步。认识默认标题栏 TitleBar三按钮与拖拽逻辑FramelessWindow默认使用TitleBar作为标题栏它的完整实现位于 qframelesswindow/titlebar/init.py。这个类继承自TitleBarBase自带三件套minBtn最小化按钮maxBtn最大化 / 还原按钮图标会随状态自动切换closeBtn关闭按钮悬停时变为红色标题栏高度固定为32px三个按钮统一为46×32尺寸。除了按钮之外TitleBarBase还内置了完整的交互逻辑比如双击标题栏空白处切换最大化状态可用setDoubleClickEnabled(False)关闭鼠标按住空白区域拖动窗口自动避开按钮区域通过canDrag()判断监听窗口状态变化实时更新最大化按钮的图标升级到 StandardTitleBar图标 标题一步到位如果你希望标题栏左侧显示窗口图标和窗口标题直接把默认标题栏替换成StandardTitleBar即可。它是TitleBar的子类在原有三按钮基础上增加了iconLabel和titleLabel两个标签from PyQt5.QtGui import QIcon from qframelesswindow import FramelessWindow, StandardTitleBar class Window(FramelessWindow): def __init__(self, parentNone): super().__init__(parentparent) # 替换默认标题栏 self.setTitleBar(StandardTitleBar(self)) self.setWindowIcon(QIcon(logo.png)) self.setWindowTitle(我的应用) self.titleBar.raise_()更贴心的是StandardTitleBar会自动监听windowIconChanged和windowTitleChanged信号——窗口图标或标题一旦变化标题栏立刻同步更新无需手动干预。当然你也可以通过setTitle()和setIcon()手动控制。如何自定义标题栏样式从按钮换色到 QSS 美化标题栏按钮都继承自TitleBarButton定义在 qframelesswindow/titlebar/title_bar_buttons.py每个按钮都有普通 / 悬停 / 按下三种状态每种状态都可独立配置图标颜色和背景色。方式一Python 方法直接设置self.minBtn.setHoverColor(Qt.white) self.minBtn.setHoverBackgroundColor(QColor(0, 100, 182)) self.minBtn.setPressedColor(Qt.white) self.minBtn.setPressedBackgroundColor(QColor(54, 57, 65))方式二QSS 属性选择器更优雅self.maxBtn.setStyleSheet( TitleBarButton { qproperty-normalColor: black; qproperty-normalBackgroundColor: transparent; qproperty-hoverColor: white; qproperty-hoverBackgroundColor: rgb(0, 100, 182); qproperty-pressedColor: white; qproperty-pressedBackgroundColor: rgb(54, 57, 65); } )由于按钮颜色都是通过pyqtProperty暴露的QSS 可以直接用qproperty-xxx语法修改非常适合做主题换肤。参考完整示例见 examples/demo.py。完整实战打造一款带图标的 CustomTitleBar把上面所有知识串起来我们就能写一个真正属于自己的自定义标题栏——在StandardTitleBar基础上换一套蓝白配色from PyQt5.QtCore import Qt from PyQt5.QtGui import QColor from qframelesswindow import FramelessWindow, StandardTitleBar class CustomTitleBar(StandardTitleBar): def __init__(self, parent): super().__init__(parent) # 给最小化按钮换上蓝色悬停效果 self.minBtn.setHoverColor(Qt.white) self.minBtn.setHoverBackgroundColor(QColor(0, 100, 182)) self.minBtn.setPressedColor(Qt.white) self.minBtn.setPressedBackgroundColor(QColor(54, 57, 65)) # 最大化与关闭按钮同理可继续扩展... class Window(FramelessWindow): def __init__(self, parentNone): super().__init__(parentparent) self.setTitleBar(CustomTitleBar(self)) # 换上新标题栏 self.setWindowIcon(QIcon(logo.png)) self.setWindowTitle(PyQt-Frameless-Window) self.titleBar.raise_()除了换色你还可以往标题栏里塞菜单栏、搜索框、工具栏等任意控件。比如 examples/main_window.py 就演示了如何把QMenuBar放进标题栏做出类似 Chrome 那种一体化顶部栏的效果。另外项目还提供了FramelessMainWindow和FramelessDialog分别对应主窗口和对话框场景。与 Qt Designer 集成记住 32px 标题栏空间如果你习惯用 Qt Designer 画界面集成也很顺畅。核心技巧只有一个在设计稿顶部为标题栏预留 32px 高度否则内容会被标题栏遮挡编译好 ui 文件后用多继承的方式组合FramelessWindow和Ui_Form即可无缝衔接具体细节可以参考 docs/source/usage.md 文档。进阶玩法macOS 系统按钮与 Acrylic 毛玻璃效果适配 macOS 原生红绿灯按钮在 macOS 上你可以隐藏自定义标题栏按钮改用系统原生按钮。此时只需重写systemTitleBarRect()方法把系统按钮区域挪到右上角参考 examples/demo.pydef systemTitleBarRect(self, size: QSize) - QRect: return QRect(size.width() - 75, 0, 75, size.height())一键开启亚克力 / Mica 模糊想要半透明毛玻璃质感换用AcrylicWindow即可examples/acrylic_demo.py 里有最小示例from qframelesswindow import AcrylicWindow class Window(AcrylicWindow): def __init__(self, parentNone): super().__init__(parentparent) self.setWindowTitle(Acrylic Window) self.titleBar.raise_() # Win11 上还可以启用 Mica 效果 # self.windowEffect.setMicaEffect(self.winId(), isDarkModeFalse, isAltFalse)Win10 使用亚克力、Win11 使用 Mica、Win7 自动回退 Aero库会自动按系统版本选择最佳效果更多细节见 docs/source/window-effect.md。常见问题与避坑指南标题栏被内容遮挡检查是否漏了self.titleBar.raise_()。Win10 下拖动亚克力窗口卡顿这是系统限制可在拖动时临时关闭亚克力效果文档提供了setAcrylicEffectEnabled()思路。菜单栏显示异常使用FramelessMainWindow时记得self.setMenuWidget(self.titleBar)并参考 examples/main_window.py 的完整写法。导入报错Windows 平台依赖 pywin32Linux 依赖 xcffibmacOS 依赖 pyobjc请先安装对应平台的依赖。从默认的TitleBar到带图标标题的StandardTitleBar再到完全自定义的CustomTitleBarPyQt-Frameless-Window 用清晰的继承体系把自定义标题栏这件事变得极其简单。现在就去动手改造你的第一个无边框窗口吧【免费下载链接】PyQt-Frameless-WindowA cross-platform frameless window based on PyQt/PySide, support Win32, Linux and macOS.项目地址: https://gitcode.com/gh_mirrors/py/PyQt-Frameless-Window创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考