CMake基础: Qt之qt5_wrap_ui

1.简介

2.核心作用与原理

3.语法与参数

4.使用示例

5.生成文件与代码使用

[6.与 AUTOUIC 的对比](#6.与 AUTOUIC 的对比)

[7.Qt6 兼容性](#7.Qt6 兼容性)

8.总结

1.简介

qt5_wrap_ui 是 Qt5 提供的CMake 低级别宏命令 ，用于调用 Qt 的 uic（User Interface Compiler） 工具，将 Qt Designer 生成的 .ui 界面描述文件转换为对应的 C++ 头文件，以便在代码中直接使用界面组件。

2.核心作用与原理

核心功能 ：为每个输入的 .ui 文件生成一个 ui_<basename>.h 头文件，包含界面类的定义（如 Ui::MainWindow）
工作流程 ：
1. 解析 .ui 文件（XML 格式）中的界面布局、控件属性和信号槽连接
2. 生成包含完整界面初始化代码的 C++ 头文件
3. 自动处理控件的父子关系、布局设置和信号槽连接
4. 生成的头文件位于构建目录中（非源文件目录）
典型用途：在手动管理 Qt 项目构建流程时，显式触发 uic 工具处理 UI 文件

3.语法与参数

基本语法：

cpp 复制代码

qt5_wrap_ui(<OUTPUT_VAR> <UI_FILE1> [UI_FILE2 ...] [OPTIONS ...])

参数	说明
`<OUTPUT_VAR>`	输出变量名，存储所有生成的头文件路径列表
`<UI_FILE>`	一个或多个 Qt Designer 生成的 `.ui` 文件路径
`OPTIONS`	可选参数，传递给 uic 工具的额外选项（如 `-tr` 指定翻译目录）

4.使用示例

1.基础用法

cpp 复制代码

# 1. 查找 Qt5 Widgets 模块
find_package(Qt5 REQUIRED COMPONENTS Widgets)

# 2. 设置包含当前构建目录（用于包含生成的 ui_*.h）
set(CMAKE_INCLUDE_CURRENT_DIR ON)

# 3. 定义源文件和 UI 文件
set(SOURCES main.cpp mainwindow.cpp)
set(UI_FILES mainwindow.ui)

# 4. 调用 qt5_wrap_ui 生成 UI 头文件
qt5_wrap_ui(UI_HEADERS ${UI_FILES})

# 5. 添加可执行文件，包含生成的 UI 头文件
add_executable(MyApp ${SOURCES} ${UI_HEADERS})

# 6. 链接 Qt5 Widgets 库
target_link_libraries(MyApp Qt5::Widgets)

2.多 UI 文件处理

cpp 复制代码

set(UI_FILES
    mainwindow.ui
    settingsdialog.ui
    aboutdialog.ui
)
qt5_wrap_ui(UI_GENERATED ${UI_FILES})
# 生成: ui_mainwindow.h, ui_settingsdialog.h, ui_aboutdialog.h

3.带 OPTIONS 示例

cpp 复制代码

# 为 uic 指定额外参数（如设置翻译目录）
qt5_wrap_ui(UI_HEADERS ${UI_FILES} OPTIONS -tr "translations" -no-autoconnection)

5.生成文件与代码使用

1.生成文件命名规则

输入文件	生成头文件	命名空间
`mainwindow.ui`	`ui_mainwindow.h`	`Ui::MainWindow`
`mywidget.ui`	`ui_mywidget.h`	`Ui::MyWidget`

2.在代码中使用生成的 UI 头文件

cpp 复制代码

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>

QT_BEGIN_NAMESPACE
namespace Ui { class MainWindow; }
QT_END_NAMESPACE

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow(QWidget *parent = nullptr);
    ~MainWindow();

private:
    Ui::MainWindow *ui;
};
#endif // MAINWINDOW_H

cpp 复制代码

#include "mainwindow.h"
#include "ui_mainwindow.h"

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent)
    , ui(new Ui::MainWindow)
{
    ui->setupUi(this);
}

MainWindow::~MainWindow()
{
    delete ui;
}

6.与 AUTOUIC 的对比

特性	qt5_wrap_ui	AUTOUIC（推荐）
类型	显式手动调用	自动处理机制
触发方式	手动调用宏，添加生成文件到目标	设置 `set(CMAKE_AUTOUIC ON)` 或 `target_property(AUTOUIC ON)`
文件管理	需手动管理生成的头文件	CMake 自动扫描 `#include "ui_*.h"` 语句，自动处理对应 `.ui` 文件
构建目录	需手动添加 `${CMAKE_CURRENT_BINARY_DIR}` 到包含路径	自动处理包含路径
适用场景	特殊需求（如自定义生成路径）	大多数 Qt 项目，简化构建流程

AUTOUIC 示例（更现代的用法）

cpp 复制代码

cmake_minimum_required(VERSION 3.5)
project(MyApp)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_AUTOUIC ON)  # 启用自动 UIC 处理
set(CMAKE_AUTOMOC ON)  # 启用自动 MOC 处理
set(CMAKE_AUTORCC ON)  # 启用自动 RCC 处理

find_package(Qt5 REQUIRED COMPONENTS Widgets)

set(SOURCES main.cpp mainwindow.cpp mainwindow.h)
set(UI_FILES mainwindow.ui)

add_executable(MyApp ${SOURCES} ${UI_FILES})  # 直接包含 .ui 文件
target_link_libraries(MyApp Qt5::Widgets)

7.Qt6 兼容性

Qt6 中提供了 qt6_wrap_ui 宏，语法与 Qt5 完全一致
Qt6 还引入了更现代的 qt_add_ui 命令，直接将 UI 文件添加到目标，无需手动管理生成文件

cpp 复制代码

# Qt6 现代用法
qt_add_ui(MyApp SOURCES mainwindow.ui)

8.总结

qt5_wrap_ui 是 Qt5 中处理 UI 文件的基础 CMake 宏，适用于需要手动控制 uic 处理流程的场景。对于大多数项目，推荐使用 AUTOUIC 自动处理机制，简化构建脚本并减少出错概率。无论使用哪种方式，核心都是通过 uic 工具将 .ui 文件转换为可在 C++ 代码中使用的界面类。