ElaWidgetTools

Fluent Design UI component library for Qt Widgets and PySide6. Build modern cross-platform desktop apps with 100+ widgets, light/dark themes, frameless navigation, routing and rich application interactions.

核心特性

• 100+ 现成组件：按钮、输入、卡片、数据展示、导航布局、弹出交互和编辑器等常用桌面控件。
• C++ 与 Python 双入口：原生 Qt Widgets 库可直接用于 C++，并通过 Shiboken6 提供可安装的 PySide6 绑定。
• 现代化桌面框架：无边框窗口、侧边导航、面包屑、声明式路由、事件总线和停靠面板。
• Fluent Design 视觉体系：Light/Dark 主题、Mica/Acrylic 材质、动效反馈和高 DPI 支持。
• 跨平台支持：覆盖 Windows、Ubuntu/Kylin 和 macOS 桌面应用场景。

快速开始

使用 Python / PySide6

pip install --upgrade ElaWidgetTools

git clone https://github.com/CyberWon/PySide6ElaWidgetTools.git
cd PySide6ElaWidgetTools
python PySide6Example/main.py

Wheel 会自动声明并依赖运行所需的 PySide6。如需从源码构建绑定，请参考下文的 PySide6 绑定。

构建 C++ 示例

git clone https://github.com/CyberWon/PySide6ElaWidgetTools.git
cd PySide6ElaWidgetTools

cmake -B build -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="/path/to/Qt/6.x/<platform-kit>"
cmake --build build --config Release --target ElaWidgetToolsExample

将 <platform-kit> 替换为本机的 Qt Kit 目录，例如 Windows 的 msvc2022_64、Linux 的 gcc_64 或 macOS 的 macos。构建产物位于 build/ElaWidgetToolsExample/。

简介

本项目基于 Liniyous/ElaWidgetTools 独立修改发展而来。

基于 Qt Widget 开发的 FluentUI 风格组件库，提供不限于组件的常用集成功能。目前共有 100+ 个公开组件，涵盖基础控件、数据展示、导航布局、弹出交互、编辑输入等类别。完整 API 文档见 doc/API.md。

支持平台

Windows	Ubuntu/Kylin	macOS

Qt 版本兼容性

⚠️ 不建议在 Windows 上使用 Qt 6.11.0。 该版本在 Windows 平台存在 Popup 窗口透明区域合成行为变更的 bug，导致使用 drawEffectShadow 绘制阴影的组件出现透明边框（macOS 不受影响）。此问题已在下一版本中修复。本项目通过 Q_OS_WIN && QT_VERSION_CHECK(6, 11, 0) 条件编译针对该版本进行了适配，但仍建议升级或使用其他版本以获得最佳体验。

主界面预览

支持的组件

基础设施

按钮与输入

数据展示

卡片

导航与布局

弹出与交互

窗口与面板

视图

编辑器与渲染

聊天与终端

系统功能

API 文档

完整的组件 API 文档由脚本自动生成，见 doc/API.md。

重新生成：

python3 scripts/generate_docs.py

PySide6 绑定

本项目提供基于 Shiboken6 的 PySide6 绑定基础设施，支持在 Python 中使用所有组件。

发布后的 wheel 可通过 PyPI 安装：

pip install ElaWidgetTools

当前发布流程覆盖 macOS（Python 3.10/3.12）和 Windows（Python 3.9-3.12）。发布与首次配置步骤见 RELEASING.md。

前置依赖

pip install PySide6 shiboken6 shiboken6-generator

构建绑定

# 生成 typesystem 和 global.h
python3 scripts/generate_bindings.py

# 构建 ElaWidgetTools 动态库
cmake -B build -DELAWIDGETTOOLS_BUILD_STATIC_LIB=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build --target ElaWidgetTools

# 运行 shiboken6 生成绑定代码，然后编译为 Python 模块
# 详细步骤参考 bindings/ 目录

Python 绑定已知限制

• ElaRouter 回调守卫 API：beforeEach / afterEach / setRouteBeforeEnter 的 参数是 std::function 回调（ElaRouteGuard / ElaRouteAfterHook），shiboken6 无法 为 std::function 生成转换代码，因此这三个方法在 Python 侧不可用。其余核心路由 API（addRoute / addRoutes / addDynamicRoute / push / replace / back / forward / removeRoute 等）均已绑定。路由跳转拦截请改用 ElaWindow.addPageNode 提前注册页面 + ElaWindow.navigation(key) 方式实现； 懒加载工厂（ElaRouteConfig.factory）在 Python 侧亦不可用，请按需创建页面后再 注册。
• ElaWindow 导航节点 out 参数：addExpanderNode / addFooterNode / addCategoryNode 的节点 key 通过 QString& out 参数回传。绑定生成阶段已通过 bindings/fix_out_params.py 自动改写，Python 侧调用约定为传 "" 占位并解包 _, key = addExpanderNode(...)，返回 (NodeResult, key) 二元组。

完整示例见 PySide6Example/ 目录。

致谢

本项目基于 Liniyous/ElaWidgetTools 修改而来，感谢原作者的开源贡献。

许可证

ElaWidgetTools 使用 MIT 许可证授权所有类型项目，但要求所有分发的软件中必须保留本项目的MIT授权许可；所有未保留授权分发的商业行为均将被视为侵权行为