PyQt-Frameless-Window 是什么？跨平台无边框窗口库完全指南

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 打造一款界面精美的桌面应用，PyQt 无边框窗口几乎是绕不开的一步。而PyQt-Frameless-Window正是这样一款帮你快速实现跨平台无边框窗口的开源库：只需继承一个类，就能让窗口支持拖动、拉伸、阴影、动画，甚至 Win11 贴靠布局和亚克力模糊效果，完美覆盖 Win32、Linux 和 macOS 三大平台。下面这份完全指南，带你从零上手。

什么是无边框窗口？为什么它这么受欢迎？

传统的桌面窗口自带系统标题栏和边框，样式固定、难以定制。而**无边框窗口（Frameless Window）**会去掉这些系统元素，让你完全掌控窗口外观——标题栏、按钮、圆角、背景全部自定义，视觉效果与主流应用（如各类音乐播放器、笔记软件）保持一致。

PyQt-Frameless-Window 的价值在于：它把"去掉边框后还能正常拖动、缩放"这一底层难点全部封装好，你不需要研究各系统底层 API，就能获得与原生窗口一致的交互体验。

核心特性一览：为什么选择它？

• 窗口拖动与拉伸：默认标题栏支持拖动窗口，四边四角可自由调整大小
• 窗口阴影：为无边框窗口补充柔和阴影，避免"贴图感"
• 窗口动画：最大化、还原时带有平滑过渡动画
• Win11 贴靠布局（Snap Layout）：悬停最大化按钮即可呼出分屏布局
• 亚克力（Acrylic）模糊：Win10 原生毛玻璃质感
• Mica 材质：Win11 专属的现代模糊效果
• Win7 Aero、macOS 模糊：老平台也能获得半透明效果

一键安装步骤：最快上手方式

安装非常简单，直接使用 pip：

pip install PyQt5-Frameless-Window

如果你使用的是 PyQt6、PySide2 或 PySide6，还可以分别安装对应的PyQt6-Frameless-Window、PySide2-Frameless-Window、PySideSix-Frameless-Window版本，一个项目四套绑定方案全部支持。

提示：不同平台需要额外依赖，Windows 需要 pywin32、Linux 需要 xcffib、macOS 需要 pyobjc，安装时会自动处理。

最快配置方法：三行代码创建无边框窗口

使用 PyQt-Frameless-Window 的核心思路只有一个：继承FramelessWindow或FramelessMainWindow。最小示例代码如下：

import sys from PyQt5.QtWidgets import QApplication from qframelesswindow import FramelessWindow class Window(FramelessWindow): def __init__(self, parent=None): super().__init__(parent=parent) self.setWindowTitle("PyQt-Frameless-Window") self.titleBar.raise_() if __name__ == '__main__': app = QApplication(sys.argv) demo = Window() demo.show() sys.exit(app.exec_())

继承之后，窗口的拖动、拉伸、阴影等功能全部自动生效，零配置。如果你需要菜单栏、状态栏、文本编辑区等功能齐全的主窗口，可以参考 examples/main_window.py 中的FramelessMainWindow完整示例，或者查看 examples/demo.py 了解更复杂的用法。

跨平台支持：一套代码，三端运行

项目的核心设计就是跨平台，源码按系统拆分为三个模块，由库自动选择：

• Windows 实现位于 qframelesswindow/windows/，通过 Win32 API 处理原生消息，如nativeEvent、WM_NCHITTEST命中测试等
• macOS 实现位于 qframelesswindow/mac/，基于 Objective-C 运行时实现拖动与缩放
• Linux 实现位于 qframelesswindow/linux/，支持 X11 与 Wayland

你只需要写一套 UI 代码，三个平台都能获得一致的无边框体验。窗口几何信息（geometry()与frameGeometry()的区别）可参考下图理解：

炫酷窗口效果：亚克力、Mica 与阴影

PyQt-Frameless-Window 内置了WindowEffect控制类和AcrylicWindow窗口类，让你轻松给窗口添加视觉特效。使用AcrylicWindow即可获得亚克力模糊背景：

from qframelesswindow import AcrylicWindow class Window(AcrylicWindow): def __init__(self, parent=None): super().__init__(parent=parent) self.setWindowTitle("Acrylic Window") self.titleBar.raise_()

在 Win11 上还可以切换为 Mica 材质，只需调用setMicaEffect()；阴影、动画、菜单阴影等功能也都能通过WindowEffect一键开启。完整效果说明见 docs/source/window-effect.md。

小贴士：在 Win10 上拖动亚克力窗口偶尔会有卡顿，官方建议拖动时临时关闭亚克力效果，文档中提供了现成的切换方法。

如何开启 Win11 贴靠布局（Snap Layout）

贴靠布局是 Win11 的招牌功能：鼠标悬停最大化按钮即可弹出分屏方案，帮助用户高效整理窗口。PyQt-Frameless-Window 默认未开启该功能（因为用户可能自定义最大化按钮），启用方法是在nativeEvent中处理最大化按钮的HTMAXBUTTON命中测试。

具体代码示例与WM_NCCALCSIZE消息处理细节，可以查阅 docs/source/snap-layout.md，其中还包含在最大化状态下正确处理窗口坐标的注意事项。效果如下：

自定义标题栏：让窗口拥有你的风格

库内置了TitleBar默认标题栏，包含最小化、最大化/还原、关闭三个按钮，按钮类定义在 qframelesswindow/titlebar/title_bar_buttons.py 中。你可以通过setXXXColor()方法或 QSS 样式表自定义按钮的悬停、按下颜色，也可以继承TitleBar重写，或用带图标和标题的StandardTitleBar替代，还能在标题栏上插入菜单栏、自定义控件。

如果配合 Qt Designer 使用，只需为标题栏预留 32px 空间，再通过多继承方式接入，详细说明见 docs/source/usage.md。

常见问题与注意事项

1. 拖动亚克力窗口卡顿：Win10 上可能出现，建议移动时禁用亚克力效果
2. 贴靠布局默认关闭：需按文档修改nativeEvent启用
3. win32api 导入失败：多为 pywin32 版本问题，升级或重装即可解决
4. 对话框类：库还提供了FramelessDialog，自动隐藏最小化、最大化按钮，适合做弹窗

总结

PyQt-Frameless-Window 是一款成熟、易用、跨平台的 PyQt 无边框窗口解决方案：继承即用、效果丰富、文档完善，社区中已有 Groove 音乐播放器、Alpha-Gobang-Zero、PyQt-Fluent-Widgets 等众多优秀项目基于它构建。无论你是想做一个漂亮的桌面小工具，还是构建大型商业应用，它都能帮你省下大量底层开发时间，让界面开发回归"好看"本身。

【免费下载链接】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