# utkwidget

**Repository Path**: maker_knz_admin/utkwidget

## Basic Information

- **Project Name**: utkwidget
- **Description**: UTK(union tool kit)是基于Qt开发的一整套简单且实用的通用开发框架，有助于开发者快速进行项目开发
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-02-28
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# utkwidget

#### 介绍
UTK(union tool kit)是基于Qt开发的一整套简单且实用的通用开发框架平台，有助于开发者快速进行项目开发，分为utkwidget、utkcore、example三个模块；

utkwidget：
基础控件库，统一样式，颜色，主题风格，支持亮色暗色主题切换，换肤效果，依赖Qt5::Core，Qt5::Widgets，Qt5Svg，Qt5Network模块

utkcore：
提供除UI以外的类的封装，比如：线程，同步，异步消息机制，xml，ini配置文件解析等，只依赖Qt5::Core模块

example：
代码示例，便于开发者快速了解如何使用

软件截图：
![输入图片说明](doc/example_light.png)
![输入图片说明](doc/example_dark.png)

#### 软件框架

![输入图片说明](utk-framework.png)

### 代码目录结构

```
├─doc                          // 文档相关
├─examples                 // 实例代码
│  ├─icons                   // 界面图标
│  ├─plugin                  // 插件模块
│  └─translations          // 翻译文件
├─libs                           // 三方库
├─packages                  // 打包相关
├─utkcore                    // Core模块
│  ├─crashhandler        // dump生成
│  ├─encrypt                // 加解密算法
│  ├─json                     // json解析
│  ├─message              // qt封装消息
│  ├─mqtt                    // mqtt协议
│  ├─plugin                  // qt封装插件解析框架
│  ├─qhttpengine         // qt封装http服务
│  ├─serializer              // qt封装序列化反序列化
│  └─thread                 // 线程相关
└─utkwidget                // Widget模块
    ├─dialog                  // dialog弹窗
    ├─effect                  // 特效
    ├─icons                   // 图标
    │  ├─dark
    │  │  └─icons
    │  └─light
    │      └─icons
    ├─images                     // 图片
    ├─logger                      // 日志模块
    ├─modelview               // 表格相关
    ├─qhotkey                   // 热键
    ├─qrencode                 // 二维码库
    ├─singleapplication     // 单程序实例
    ├─style                        // 样式相关
    ├─translations             // 翻译
    ├─widgets                  // 基础控件
    └─zip                         // 压缩解压
```

#### 版本

1.  cmake 3.10 + Qt 5.15.2

#### 开发规范

1.  utkcore和utkwidget两个模块中类名必须以U开头，必须使用Q指针和D指针，私有类、私有成员、私有方法不要在头文件中暴露；
2.  图标规范：深色图标放置目录:/icons/dark/icons/；亮色图标放置目录：/icons/light/icons/；添加图标文件后，在程序中使用 QIcon::fromTheme(“utk_xxx”) 获取当前主题对应的图标对象，“utk_xxx” 为图标文件名称，不包含文件后缀名；
3.  翻译文件放置在translations目录下且只上传ts文件；
4.  代码中使用颜色首选UPalette类以及颜色枚举，禁止直接用色值；
5.  头文件需要添加注释，方便后续用Doxygen生成文档；
6.  开发过程中需要图标可以到[阿里巴巴矢量图标库](https://www.iconfont.cn/?spm=a313x.search_index.i3.2.19263a81P9idc9)下载；
7.  代码严格按照C++和Qt代码规范进行开发；

#### 效果展示（Qt控件对应关系）
![输入图片说明](doc/1750555894087.jpg)

![输入图片说明](doc/1750555991393.jpg)

![输入图片说明](doc/1750556071246.jpg)

### 关键代码（ **只提供核心类和接口，完整代码请看源码** ）

1. 颜色类（禁止使用颜色值硬编码，统一使用颜色枚举）：

```
class UTKWIDGET_EXPORT UPalette : public QPalette
{
    Q_GADGET
public:
    enum ColorType
    {
        NoType = 100,
        ItemBackground,                //列表项的背景色
        SuccessBackground,              //成功色
        WarningBackground,             //告警色
        ErrorBackground,               //错误色
        OrangeBackground,              //橙色
        OfflineBackground,             //离线状态颜色（灰色）
        InformationBackground,         //信息色
        MenuBackground,                //菜单栏色
        ModuleBackground,              //模块背景色
        SplitLineBackground,           //分割线颜色
        NColorTypes
    };
    Q_ENUM(ColorType)

    const QColor color(int ct) const;

    const QColor color(ColorGroup cg, int ct) const;
}；
```
2. **控件样式使用QStyle实现，禁止使用样式表，主要包括（UProxyStyle，UStyleOption，UStylePainter）** ：

1）自定义控件枚举：
```
    enum UPrimitiveElement
    {
        PE_ItemBackground = QStyle::PE_CustomBase + 100,
        PE_IndicatorCheckBox,
        PE_IndicatorRadioButton,
        PE_SettingsItem,
        PE_UScrollBar
    };
    Q_ENUM(UPrimitiveElement)

    enum UControlElement
    {
        CE_UIconButton = QStyle::CE_CustomBase + 100,
        CE_RadioButton,
        CE_CheckBox,
        CE_UCommonButton,
        CE_UTagWidget
    };
    Q_ENUM(UControlElement)

    enum UPixelMetric
    {
        PM_FocusBorderWidth = QStyle::PM_CustomBase + 100,        //控件焦点状态的边框宽度
        PM_FocusBorderSpacing,                                  //控件内容和border之间的间隔
        PM_FrameRadius,                                         //控件的圆角大小
        PM_ShadowRadius,                                        //控件阴影效果的半径
        PM_FrameMargins                                         //控件的margins区域，控件内容 = 控件大小 - FrameMargins
    };
    Q_ENUM(UPixelMetric)

    enum UComplexControl
    {
        CC_UScrollBar = QStyle::CC_CustomBase + 100
    };
    Q_ENUM(UComplexControl)

    // 主要接口
    void drawControl(ControlElement element, const QStyleOption* option,
                     QPainter* painter, const QWidget* widget) const override;

    void drawControl(UControlElement element, const QStyleOption* option,
                     QPainter* painter, const QWidget* widget) const;

    void drawPrimitive(PrimitiveElement element, const QStyleOption* option,
                       QPainter* painter, const QWidget* widget = nullptr) const override;

    void drawPrimitive(UPrimitiveElement element, const QStyleOption* option,
                       QPainter* painter, const QWidget* widget = nullptr) const;

    void drawComplexControl(ComplexControl control, const QStyleOptionComplex* option,
                            QPainter* painter, const QWidget* widget = nullptr) const override;

    void drawComplexControl(UComplexControl control, const QStyleOptionComplex* option,
                            QPainter* painter, const QWidget* widget = nullptr) const;
```
2）UStyleOption，以Button为例：

```
class UTKWIDGET_EXPORT UCommonButtonOption : public QStyleOptionButton
{
public:
    enum ButtonFeature
    {
        PlainButton = (CommandLinkButton << 1),
        DeepButton = (PlainButton << 1),
        LightButton = (DeepButton << 1),
        UCommandLinkButton = (LightButton << 1)
    };

    QColor backgroundColor;
    QColor foregroundColor;
    QColor borderColor;
    int radius;
    RadiuPosition position;
    uint alignment;

    UCommonButtonOption();
};
```
3）UTheme主题切换类，主要用于换肤：

```
class UTKWIDGET_EXPORT UTheme
{
public:
    UTheme();
    ~UTheme();

    enum ThemeType
    {
        LightTheme,
        DarkTheme
    };

    ThemeType theme() const;
    void setTheme(const ThemeType &type);

    UPalette* palette() const;

    QString themeName() const;

private:
    QScopedPointer<UThemePrivate> d_ptr;
    Q_DECLARE_PRIVATE(UTheme)
};
```
3. 插件相关

1）UPluginManager插件管理类，主要用于插件路径设置，插件加载，获取插件对象等

```
class UTKCORE_EXPORT UPluginManager : public QObject
{
    Q_OBJECT
public:
    static UPluginManager* instance();

    void addObject(QObject* obj);
    void removeObject(QObject* obj);
    QList<QObject*> allObjects();
    QList<UPluginInfo*> allPlugins();
    QReadWriteLock* listLock();
    QObject* getObjectByName(const QString &name);
    QObject* getObjectByClassName(const QString &className);

    void loadPlugins();
    QStringList pluginPaths();
    void setPluginPaths(const QStringList &paths);
    bool hasError();

    bool isInitializationDone();

    void shutdown();

signals:
    void objectAdded(QObject* obj);
    void aboutToRemoveObject(QObject* obj);

    void pluginsChanged();
    void initializationDone();
};
```
2）UPluginInfo单个插件信息类，主要用于单个插件库信息读取和加载

```
class UTKCORE_EXPORT UPluginInfo : public QObject
{
    Q_OBJECT
public:
    explicit UPluginInfo(QObject* parent = nullptr);
    ~UPluginInfo();

    bool loadLibrary();

    bool read(const QString &file);

    UIPlugin* iPlugin();

    QString iPluginName();

    bool isError();

    bool unload();

    QJsonObject pluginInfo() const;

private:
    QScopedPointer<UPluginInfoPrivate> d_ptr;
    Q_DECLARE_PRIVATE(UPluginInfo)
};
```
3）UIPlugin插件类，使用时需要继承该基类

```
class UTKCORE_EXPORT UIPlugin : public QObject
{
    Q_OBJECT

public:
    explicit UIPlugin(QObject *parent = nullptr) {}
    virtual ~UIPlugin() {}

    virtual int type() const = 0;

    virtual QString name() const = 0;

    virtual void initializationFinished() = 0;

    virtual QObject* createObject(const QString &name = QString(), QObject* parent = nullptr) = 0;
};

#define interface_iid "org.pluginqt.custompluginuse.utk.utkplugin1.0.0"
Q_DECLARE_INTERFACE(UIPlugin, interface_iid)
```

4. AES加解密（基于OpenSSL封装）：

```
class UTKCORE_EXPORT UAESEncrypt
{
public:
    enum AESType {
        AES_128,
        AES_192,
        AES_256,
    };

    enum AESMode {
        AES_ECB,
        AES_CBC,
        AES_CFB,
        AES_OFB
    };

    enum AESPadding {
        AES_PKCS7,
        AES_ISO7816_4,
        AES_ANSI923,
        AES_ISO10126,
        AES_ZERO,
    };

    UAESEncrypt();
    UAESEncrypt(AESType type, AESMode mode, AESPadding padding);
    ~UAESEncrypt();

    QByteArray decrypt(QByteArray cyphertext, const QByteArray &key, const QByteArray &iv);

    QByteArray encrypt(QByteArray plaintext, const QByteArray &key, const QByteArray &iv);

    QString GetLastError();
};
```
5. RC2加解密：
```
class UTKCORE_EXPORT URC2Encrypt
{
public:
    URC2Encrypt();
    ~URC2Encrypt();

    QByteArray decrypt(QByteArray cyphertext, const unsigned char* key, const unsigned char* iv);

    QByteArray encrypt(QByteArray plaintext, const unsigned char* key, const unsigned char* iv);

    QString GetLastError();
};
```
6. RSA加解密：

```
class UTKCORE_EXPORT URSAEncrypt
{
public:
    URSAEncrypt();
    ~URSAEncrypt();

    void generateRSAKeys(int length, const QString &publicKeyFile, const QString &privateKeyFile);

    QByteArray encryptByPubkeyString(const QByteArray &message, const QByteArray &pubkey);

    QByteArray encryptByPubkeyFile(const QByteArray &message, const std::string &pub_filename);

    QByteArray encryptByPrikeyString(const QByteArray &message, const QByteArray &prikey);

    QByteArray encryptByPrikeyFile(const QByteArray &message, const std::string &pri_file);

    QByteArray decryptByPubkeyString(const QByteArray &cipher, const QByteArray &pubkey);

    QByteArray decryptByPubkeyFile(const QByteArray &cipher, const std::string &pub_filename);

    QByteArray decryptByPrikeyString(const QByteArray &cipher, const QByteArray &prikey);

    QByteArray decryptByPrikeyFile(const QByteArray &cipher, const std::string &pri_file);

    QString GetLastError();
};
```
7. HTTP客户端请求封装：

```
// UHttpClient请求类
class UTKCORE_EXPORT UHttpClient : public QObject, public HttpInterface
{
public:
    static UHttpClient* instance();
    
     // 同步get请求
    bool getSync(const QString &url, QByteArray &resopnse, const QUrlQuery &urlQuery = QUrlQuery()) override;

    // 异步get请求
    void getAsync(const QString &url, std::function<void (int, QByteArray)> resopnse,
                  const QUrlQuery &urlQuery = QUrlQuery()) override;
    // 异步get请求
    void getAsync(const QString &url, std::function<void (int, QByteArray)> progress,
                  std::function<void (int, QByteArray)> finished, const QUrlQuery &urlQuery = QUrlQuery()) override;

    // 同步post请求
    bool postSync(const QUrl &url, const QByteArray &data, QByteArray &result) override;

    // 异步post请求
    void postAsync(const QUrl &url, const QByteArray &data, std::function<void (int, QByteArray)> resopnse) override;

    // 同步put请求
    bool putSync(const QUrl &url, const QByteArray &data, QByteArray &result) override;

    // 异步put请求
    void putAsync(const QUrl &url, const QByteArray &data, std::function<void (int, QByteArray)> resopnse) override;

    // 设置超时时间
    void setTimeOut(int timeout) override;

    // 取消请求
    void cancelRequest() override;

    // 上传文件
    bool uploadFile(const QUrl &url, const QString &filePath) override;

    // 下载文件
    bool downloadFile(const QUrl &url, const QString &filePath, std::function<void(int)> resopnse) override;
};
```

#### Build

 **Windows MinGW** 
```
mkdir build
cd build
cmake .. -G "MinGW Makefiles" -DCMAKE_INSTALL_PREFIX=C:\package -DCMAKE_BUILD_TYPE=Release
cmake --build . --parallel --target install
```
 **Windows MSVC** 

```
mkdir build
cd build
cmake .. -G "Visual Studio 2017 15 Win64" -DCMAKE_INSTALL_PREFIX=C:\package
cmake --build . --parallel --target install --config Release
```
 **Linux** 

```
mkdir build 
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/d/library -DCMAKE_BUILD_TYPE=Release
cmake --build . --target install
```

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)

### 联系作者

作者：YaphetsHL

欢迎联系我，乐于提供技术咨询服务，可洽谈技术支持、商业合作。

QQ: 2454264168

邮箱: 2454264168@qq.com

WX: luck3692012