一套代码三端运行PyQt-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如果你用 PyQt/PySide 开发过桌面软件一定纠结过这个问题如何做出一个既好看又能自由拖动的跨平台无边框窗口系统自带的标题栏千篇一律而自己实现无边框窗口又要在 Windows、Linux、macOS 三端分别处理拖动、缩放、阴影等细节踩坑无数。今天要介绍的PyQt-Frameless-Window正是为解决这个痛点而生的开源项目——它基于 PyQt5/PyQt6/PySide一套代码即可在 Win32、Linux 和 macOS 上运行出功能完整的无边框窗口帮你彻底告别平台差异带来的烦恼。什么是无边框窗口为什么要用它无边框窗口Frameless Window指的是去掉系统原生标题栏和边框、由开发者完全自绘外观的窗口。它几乎是现代桌面应用的标准配置优点十分明显视觉统一标题栏、按钮样式与界面整体风格融为一体观感更专业体验更佳支持自定义最小化、最大化、关闭按钮还能做深色模式自由布局为后续接入毛玻璃、亚克力等高级特效打下基础但难点在于Qt 自带的setWindowFlags(Qt.FramelessWindowHint)虽然能去掉边框却同时丢掉了拖动、缩放、阴影等系统能力需要开发者自己调用底层 API 补齐工作量极大。PyQt-Frameless-Window 的核心功能一览这个库把三端底层差异全部封装好对外提供统一接口核心能力包括功能说明窗口拖动按住任意位置即可移动窗口边缘缩放支持 8 个方向的拖拽调整大小窗口阴影自动生成柔和阴影替代系统边框窗口动画最小化/还原时的平滑过渡Win11 贴靠布局悬停最大化按钮弹出 Snap Layout亚克力/云母效果Win10 亚克力、Win11 Mica、Win7 AeromacOS 模糊原生毛玻璃背景所有平台相关的逻辑都隔离在独立的模块中Windows 实现在 qframelesswindow/windows/init.py、Linux 在 qframelesswindow/linux/window_effect.py、macOS 在 qframelesswindow/mac/window_effect.py。库的入口 qframelesswindow/init.py 会根据当前系统自动选择正确的实现类对使用者完全透明。一键安装最快的配置方法安装非常简单直接用 pip 即可且为不同 Qt 绑定提供了对应包名# PyQt5 用户 pip install PyQt5-Frameless-Window # PyQt6 / PySide2 / PySide6 用户 pip install PyQt6-Frameless-Window pip install PySide2-Frameless-Window pip install PySideSix-Frameless-Window也可以克隆仓库后本地安装git clone https://gitcode.com/gh_mirrors/py/PyQt-Frameless-Window python setup.py install各平台依赖说明平台所需依赖Win32pywin32LinuxxcffibmacOSpyobjc其中 Linux 依赖 xcffibXCB 协议绑定仅在 X11 环境下工作。项目要求 Python 3.6建议使用较新的 Qt 版本以获得最佳兼容性。快速上手5 分钟创建你的第一个无边框窗口使用方式极其简单——只需要继承FramelessWindow或FramelessMainWindow即可。完整代码如下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_()很关键——它把自定义标题栏置于所有控件之上防止被遮挡。如果业务上有菜单栏、状态栏需求直接继承FramelessMainWindow即可参考 examples/main_window.py 里的写法。自定义标题栏做出你自己的风格默认的TitleBar自带最小化、最大化/还原、关闭三个按钮按钮继承自TitleBarButton定义见 qframelesswindow/titlebar/title_bar_buttons.py你可以用setXXXColor()或 QSS 轻松改样式from qframelesswindow import FramelessWindow, TitleBar from PyQt5.QtCore import Qt from PyQt5.QtGui import QColor class CustomTitleBar(TitleBar): def __init__(self, parent): super().__init__(parent) self.minBtn.setHoverColor(Qt.white) self.minBtn.setHoverBackgroundColor(QColor(0, 100, 182))想要带图标和文字的标准标题栏换成StandardTitleBar即可窗口图标和标题改变时会自动同步。更完整的定制示例见 examples/demo.py。亚克力毛玻璃效果让窗口更有质感库提供了AcrylicWindow类一行继承就能获得亚克力毛玻璃背景from qframelesswindow import AcrylicWindow class Window(AcrylicWindow): def __init__(self, parentNone): super().__init__(parentparent) self.setWindowTitle(Acrylic Window) self.titleBar.raise_() # 自定义亚克力颜色 # self.windowEffect.setAcrylicEffect(self.winId(), 106EBE99)在 Win11 上还可以启用云母Mica特效self.windowEffect.setMicaEffect(self.winId(), False)。所有特效都由WindowEffect类统一管理文档见 docs/source/window-effect.md。⚠️ 小提示Win10 下拖动亚克力窗口可能卡顿可以在拖动时临时关闭特效松开后再恢复。开启 Win11 贴靠布局Snap LayoutSnap Layout 是 Win11 的招牌功能——悬停最大化按钮即可选择窗口分屏布局。库默认未开启该功能避免与自定义按钮冲突开启方法是在 Windows 消息处理中做少量改造让鼠标悬停最大化按钮时返回HTMAXBUTTON完整代码见 docs/source/snap-layout.md。需要注意的是窗口最大化后尺寸可能超出屏幕判断按钮位置时应使用self.titleBar.childAt(pos - self.geometry().topLeft())而非简单的坐标比较原理示意图见 docs/source/_static/geometry.png。配合 Qt Designer可视化设计无边框界面喜欢用 Qt Designer 拖拽设计同样支持只需在setupUi中给顶部预留32px高度的标题栏空间设置setContentsMargins(-1, 32, -1, -1)再通过多继承组合即可class Window(FramelessWindow, Ui_Form): def __init__(self, parentNone): super().__init__(parent) self.setupUi(self)这样就能在可视化编辑器中布局主界面同时又享受到无边框窗口的全部能力两全其美。跨平台开发避坑指南高 DPI 适配启动应用前务必设置高分屏缩放策略详见 examples/demo.py 开头的写法macOS 特殊处理mac 上系统按钮位于左上角需要调用setSystemTitleBarButtonVisible(True)并隐藏自绘按钮窗口遮挡问题所有内容控件添加完毕后务必再调用一次self.titleBar.raise_()原生窗口兼容若界面包含 WebEngine 等原生窗口控件建议在app上设置Qt.AA_DontCreateNativeWidgetSiblings参考 examples/main_window.py总结PyQt-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），仅供参考