# QtQuick_QML_HuskarUI

**Repository Path**: kid-kid/qt-quick_-qml_-huskar-ui

## Basic Information

- **Project Name**: QtQuick_QML_HuskarUI
- **Description**:  第三方开源控件库HuskarUI移植模板，qml&C++。
- **Primary Language**: QML
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-14
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: QtQuick-QML-HuskarUI控件库移植使用

## README

# 使用 HuskarUI 库指南

本文档介绍了如何在您的 Qt Quick 项目中引用和使用 HuskarUI UI 组件库。

![1765695841865](image/README/1765695841865.png)

移植后的效果：

![1765696093900](image/README/1765696093900.png)

可以参考下面地址，下载相应的源码和编译好的库文件。

[HusKarUI开源项目地址](https://github.com/mengps/HuskarUI/blob/master/README-zh_CN.md)：[https://github.com/mengps/HuskarUI/blob/master/README-zh_CN.md](https://github.com/mengps/HuskarUI/blob/master/README-zh_CN.md)，具体怎么使用仓库也有介绍，下面就是介绍如何添加到自己的项目中。

**准备工作：**

到上面链接下载下来源码。

如果需要参考源码怎么使用可以到release页面下载上图所示的实例程序。

![1765696015365](image/README/1765696015365.png)

## 项目结构要求

为了正确使用 HuskarUI 库，您需要确保以下：

###### 1.创建的项目是release的，因为下载的library是release的否则运行会失败

###### 2.库文件整个直接拷贝到CMakelist.txt同级目录下即可，如果不是那就需要更改CMakelist中的包含以及库路径

![1765696435403](image/README/1765696435403.png)

![1765696529149](image/README/1765696529149.png)

## 集成步骤

### 1. 配置 CMakeLists.txt 文件

要在您的项目中使用 HuskarUI，需要对 `CMakeLists.txt` 文件进行如下修改：

#### 1.1 设置 HuskarUI 路径并包含头文件

```cmake
# 设置 HuskarUI 根目录路径，设置为`CMakeLists.txt`同级目录下的HuskarUI文件夹
set(HUSKARUI_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/HuskarUI")
# 包含头文件目录
include_directories("${HUSKARUI_ROOT}/include")
```

#### 1.2 配置 QML 导入路径

```cmake
# 确保运行时 QML 可以导入 HuskarUI.Basic
set(QML_IMPORT_PATH "${HUSKARUI_ROOT}/qml" CACHE PATH "QML import path" FORCE)
```

#### 1.3 链接 HuskarUI 静态库

在 `target_link_libraries` 命令中添加 HuskarUI 库，这个一定要在导入头文件之后链接：

```cmake
target_link_libraries(appuntitled2
    PRIVATE Qt6::Quick
    # 链接 HuskarUI 预编译库
    PRIVATE "${HUSKARUI_ROOT}/lib/HuskarUIBasic.lib"
)
```

完整的 CMakeLists.txt 示例：

```cmake
cmake_minimum_required(VERSION 3.16)

project(untitled2 VERSION 0.1 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 6.5  REQUIRED COMPONENTS Quick)

# Use prebuilt HuskarUI package placed under project root
set(HUSKARUI_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/HuskarUI")
include_directories("${HUSKARUI_ROOT}/include")
# Ensure QML can import HuskarUI.Basic at runtime
set(QML_IMPORT_PATH "${HUSKARUI_ROOT}/qml" CACHE PATH "QML import path" FORCE)

qt_standard_project_setup(REQUIRES 6.5)

qt_add_executable(appuntitled2
    main.cpp
)

qt_add_qml_module(appuntitled2
    URI untitled2
    VERSION 1.0
    QML_FILES
        Main.qml
)



# Qt for iOS sets MACOSX_BUNDLE_GUI_IDENTIFIER automatically since Qt 6.1.
# If you are developing for iOS or macOS you should consider setting an
# explicit, fixed bundle identifier manually though.
set_target_properties(appuntitled2 PROPERTIES
#    MACOSX_BUNDLE_GUI_IDENTIFIER com.example.appuntitled2
    MACOSX_BUNDLE_BUNDLE_VERSION ${PROJECT_VERSION}
    MACOSX_BUNDLE_SHORT_VERSION_STRING ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}
    MACOSX_BUNDLE TRUE
    WIN32_EXECUTABLE TRUE
)

target_link_libraries(appuntitled2
    PRIVATE Qt6::Quick

)

# 在 Qt6::Quick 链接之后，链接 HuskarUI 预编译库
target_link_libraries(appuntitled2 PRIVATE "${HUSKARUI_ROOT}/lib/HuskarUIBasic.lib")



include(GNUInstallDirs)
install(TARGETS appuntitled2
    BUNDLE DESTINATION .
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

```

### 2.在main.cpp增加初始化以及头文件，如下所示：

```cpp
 #include "HuskarUI/husapp.h" //cmakelist中已经指定了include位置，这里路径要引用正确

 int main(int argc, char *argv[])
 {
     ...
     /*! Set OpenGL, optional */
     QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL);
     QQuickWindow::setDefaultAlphaBuffer(true);
     ...
     QGuiApplication app(argc, argv);
     QQmlApplicationEngine engine;
     HusApp::initialize(&engine);
     ...
 }
```

### 3. 在 QML 文件中导入和使用 HuskarUI 组件

要在 QML 文件中使用 HuskarUI 组件，请按以下方式进行操作：

#### 3.1 导入 HuskarUI.Basic 模块

在 QML 文件顶部添加导入语句：

```qml
import QtQuick
import HuskarUI.Basic
```

#### 3.2 使用 HuskarUI 组件

现在您可以使用任何 HuskarUI 提供的组件，例如：

```qml
HusWindow {
    visible: true
    width: 1000
    height: 800
    title: qsTr("Hello World")

    HusButton {
        text: qsTr("默认按钮")
        anchors.centerIn: parent
    }
}
```

完整示例：

```qml
import QtQuick
import HuskarUI.Basic

HusWindow {
    visible: true
    width: 1000
    height: 800
    title: qsTr("Hello World")

    Column {
        anchors.centerIn: parent
        spacing: 10

        HusRadioBlock {
            id: sizeHintRadio
            initCheckedIndex: 1
            model: [
                { label: 'Small', value: 'small' },
                { label: 'Normal', value: 'normal' },
                { label: 'Large', value: 'large' },
            ]
        }

        Row {
            spacing: 15

            HusButton {
                text: qsTr('默认')
                sizeHint: sizeHintRadio.currentCheckedValue
            }

            HusButton {
                text: qsTr('主要')
                type: HusButton.Type_Primary
                sizeHint: sizeHintRadio.currentCheckedValue
            }
        }
    }
}
```

## 可用组件

HuskarUI 提供多种 UI 组件，包括但不限于：

- 按钮类: `HusButton`, `HusIconButton`, `HusButtonBlock`
- 输入类: `HusInput`, `HusTextArea`, `HusSelect`
- 布局类: `HusWindow`, `HusCard`, `HusDivider`
- 反馈类: `HusMessage`, `HusNotification`, `HusModal`
- 导航类: `HusMenu`, `HusTabView`, `HusBreadcrumb`

更多组件请参考 `HuskarUI/qml/HuskarUI/Basic/imports/` 目录中的文件。

## 注意事项

1. 确保 HuskarUI 文件夹位于项目根目录下
2. 确保链接了正确的 HuskarUI 库文件 (`HuskarUIBasic.lib`)
3. 在 QML 中导入 `HuskarUI.Basic` 模块后方可使用组件
4. 如果移动了 HuskarUI 文件夹位置，请相应更新 `HUSKARUI_ROOT` 路径