README-zh_CN.md

「 HuskarUI 」 基于 Qml 的现代 UI

Qt Qml 的 Ant 设计组件库

如果你需要 Python 实现 HuskarUI for PySide6

如果你需要 Qt5 实现 HuskarUI for Qt5

English | 中文

🌈 陈列室预览

✨ 特性

• 📦 一套开箱即用的优质 Qml 组件.
• 🎨 强大的主题定制系统.
• 💻 基于Qml，完全跨平台.
• 🔧 高度灵活的基于委托的组件定制.
• 🤖 AI 辅助开发支持.

🗺️ 路线图

开发计划可以在这里看到: 组件路线图.

任何人都可以通过 issue/qq群/wx群 进行讨论, 最终有意义的组件/功能将添加到开发计划.

🤖 AI Agent 辅助开发

Note

智能体技能

本仓库提供了两个智能体技能：

• huskarui：通过 Python 从仓库元数据中查询 HuskarUI 组件的文档、属性和示例。
• qmlpreviewer：使用 qmlscene 预览当前编辑的 QML文件，并捕获运行截图到剪贴板。

它们专为 Claude Code、Codex 等 AI Agent 编程工具设计。它可以帮助你：

• 快速查询组件文档和属性
• 获取场景化的开发示例
• 自动迭代并预览代码

👉 查看 AI Agent 技能使用指南 了解更多。

🔖 在线文档

• 组件文档

🌐 在线 Wiki

• HuskarUI 在线 Wiki (AI)

📺 在线演示

• 哔哩哔哩

🗂️ 预编译包

预编译了两个平台的 Windows / Linux 程序包和二进制库包.

前往 Release 中下载.

🔨 如何构建

• 克隆

git clone --recursive https://github.com/mengps/HuskarUI.git

• 构建 & 安装
  • Windows - Visual Studio

  cd HuskarUI
  cmake -DCMAKE_PREFIX_PATH=<QT_DIR> -G "Visual Studio <version>" -B build -S . 
  cmake --build build --config Release --target ALL_BUILD INSTALL --parallel

  • All - Ninja

  cd HuskarUI
  cmake -DCMAKE_PREFIX_PATH=<QT_DIR> -G "Ninja" -B build -S . 
  cmake --build build --config Release --target all install --parallel

Important

默认情况下, INSTALL_HUSKARUI_IN_DEFAULT_LOCATION=ON:

• headers 将安装在 [QtDir]/[QtVersion]/[Kit]/include/HuskarUI 目录中.
• *.dll 将安装在 [QtDir]/[QtVersion]/[Kit]/bin 目录中.
• *.lib/*.so/*.dylib 将安装在 [QtDir]/[QtVersion]/[Kit]/lib 目录中.
• qmlplugin 将安装在 [QtDir]/[QtVersion]/[Kit]/qml 目录中.

如果您想改变安装目录, 请将 INSTALL_HUSKARUI_IN_DEFAULT_LOCATION 设置为 OFF 并在 cmake 中设置 HUSKARUI_INSTALL_DIRECTORY.

cmake -DCMAKE_PREFIX_PATH=<QT_DIR> \
  -DINSTALL_HUSKARUI_IN_DEFAULT_LOCATION=OFF \
  -DHUSKARUI_INSTALL_DIRECTORY=<install_dir> \
  -G "Ninja" -B build -S .

安装目录结构

──<install_dir>
    ├─include
    │   └─HuskarUI/*.h
    ├─bin
    │   *.dll
    ├─lib
    │   *.lib/*.so/*.dylib
    │   └─cmake/*.cmake
    └─qml
        └─HuskarUI/Basic
        └─HuskarUI/Impl

• 用法
  • 使用 cmake 添加下面的 cmake 命令到您项目的 CMakeLists.txt 中

    find_package(HuskarUI REQUIRED)
    target_link_libraries(<your_target> HuskarUI::Basic)

  • 直接使用库
    • 链接<install_dir>/lib.
    • 包含 <install_dir>/include.
    • [可选] 复制 <install_dir>/bin/HuskarUIBasic.[dll] 到 [QtDir]/[QtVersion]/[Kit]/bin.
    • [可选] 复制 <install_dir>/lib/HuskarUIBasic.[so/dylib] 到 [QtDir]/[QtVersion]/[Kit]/bin.
    • 复制 <install_dir>/qml/HuskarUI 到 [QtDir]/[QtVersion]/[Kit]/qml.

📦 上手

• 创建 QtQuick 应用 QtVersion >= 6.7
• 添加下面的代码到您的 main.cpp 中

 #include "HuskarUI/husapp.h"

 int main(int argc, char *argv[])
 {
     ...
     /*! 设置 OpenGL, 可选 */
     QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL);
     QQuickWindow::setDefaultAlphaBuffer(true);
     ...
     QGuiApplication app(argc, argv);
     QQmlApplicationEngine engine;
     ...
 }

• 添加下面的代码到您的 .qml 中

 import HuskarUI.Basic
 HusWindow { 
   ...
 }

好了，你现在可以愉快的开始使用 HuskarUI 了。

🚩 参考

• Ant-d 组件: https://ant-design.antgroup.com/components/overview-cn
• Ant 设计: https://ant-design.antgroup.com/docs/spec/introduce-cn

💓 许可证

使用 MIT LICENSE

🌇 环境

Windows 11 / Ubuntu 24.04.2, Qt Version >= 6.7

🎉 Star 历史