C++基于微服务脚手架的视频点播系统---客户端（4）

Qt自定义控件：从零构建高级页面切换按钮

在现代GUI应用程序开发中，用户界面的交互性和美观性至关重要。一个常见的需求是实现导航栏或工具栏，用户通过点击按钮来切换不同的功能页面。虽然Qt提供了标准的QPushButton，但在追求高度定制化的界面时，其功能和样式往往受限。本文将深入探讨如何通过封装一个新的控件，从零开始构建一个集图片、文本、点击事件和高亮状态于一体的高级页面切换按钮。

一、自定义控件的设计与基础搭建

我们的目标是创建一个可复用的控件，该控件内部集成一个图片展示区和一个文本标签。当用户点击这个控件时，它能发出一个信号，通知主程序切换到指定的页面。

1.1 项目文件结构

首先，需要在项目中添加新的C++类文件来承载自定义控件的逻辑。这个过程通过Qt Creator的向导来完成，确保了项目结构的规范性。

上图展示了在Qt Creator中选择"添加新文件"的界面。我们选择"C++ Class"模板，这将为我们自动生成一个头文件（.h）和一个源文件（.cpp），这是C++面向对象编程的标准实践。

1.2 类定义与继承

接下来是定义新类的名称和其基类。这是控件封装的关键一步，基类的选择决定了自定义控件继承的基础特性。

在"类定义"对话框中，我们将类名设置为PageSwitchButton，这个名称直观地反映了其功能。初始阶段，选择QWidget作为基类是一个常见的起点，因为QWidget是所有Qt界面对象的基石，提供了最基本的窗口部件功能。勾选"添加到项目中"以确保CMakeLists.txt或.pro文件会自动更新，将新文件纳入编译体系。

1.3 控件内部组件的声明

控件的核心是展示图片和文本。QLabel是Qt中用于显示文本和图片的理想选择。因此，在PageSwitchButton的头文件（pageswitchbutton.h）中，我们声明两个QLabel指针作为私有成员变量。

cpp 复制代码

private:
    QLabel* btnImage; // 用于显示按钮的图片
    QLabel* btnTittle; // 用于显示按钮的文本

如上图所示，这两个成员变量btnImage和btnTittle被声明在private区域，遵循了面向对象封装的原则，即外部代码不应直接访问控件的内部实现细节。

1.4 控件内部布局与初始化

在PageSwitchButton的构造函数（位于pageswitchbutton.cpp）中，需要对控件本身和其内部的两个QLabel进行初始化和布局。

cpp 复制代码

// 设置按钮的固定大小
setFixedSize(48, 46); // (宽, 高)

// 创建图片标签并设置其几何位置
btnImage = new QLabel(this); // 'this'指定父对象，实现自动内存管理
btnImage->setGeometry((48 - 24) / 2, 0, 24, 24); // (x, y, 宽, 高)

// 创建文本标签并设置其几何位置
btnTittle = new QLabel(this);
btnTittle->setGeometry(0, 30, 48, 16); // (x, y, 宽, 高)

代码的解析如下：

setFixedSize(48, 46)：为整个PageSwitchButton控件设置一个固定的宽度和高度。这有助于在父窗口中进行统一和可预测的布局。
new QLabel(this)：在创建QLabel实例时，将this（即PageSwitchButton对象本身）作为其父对象。这是Qt对象树（Object Tree）内存管理机制的核心。当父对象被销毁时，其所有子对象也会被自动销毁，有效避免了内存泄漏。
setGeometry()：此函数用于手动设置子控件的位置和大小。
- btnImage->setGeometry((48 - 24) / 2, 0, 24, 24)：图片标签的宽度和高度被设为24x24。为了使其在水平方向上居中，其x坐标被计算为(父控件宽度 - 自身宽度) / 2，即(48 - 24) / 2 = 12。y坐标为0，使其位于控件顶部。
- btnTittle->setGeometry(0, 30, 48, 16)：文本标签的x坐标为0，宽度为48，使其横向占满整个控件。y坐标为30，使其位于图片标签的下方。

经过这一步，控件的内部结构已经搭建完成，具备了显示图片和文本的基础框架。

二、功能接口的封装与实现

为了让外部能够方便地设置按钮的图片和文本，我们需要提供一个公共的接口函数。

2.1 接口函数的声明

在pageswitchbutton.h文件中，声明一个公共方法setImageAndText。

cpp 复制代码

public:
    void setImageAndText(const QString& imagePath, const QString& text);

该函数接收两个const QString&类型的参数，分别代表图片资源的路径和要显示的文本。使用常量引用（const &）可以避免不必要的字符串复制，提高性能。

2.2 接口函数的实现

在pageswitchbutton.cpp文件中，实现这个接口函数。

cpp 复制代码

void PageSwitchButton::setImageAndText(const QString &imagePath, const QString &text)
{
    btnImage->setPixmap(QPixmap(imagePath)); // 加载并显示图片
    btnTittle->setText(text); // 设置并显示文本
}

btnImage->setPixmap(QPixmap(imagePath))：QPixmap是Qt中专门为在屏幕上显示图像而设计的类，经过了高度优化。此行代码首先从指定的imagePath创建一个QPixmap对象，然后调用QLabel的setPixmap方法将其显示出来。图片路径通常使用Qt的资源系统（例如":/images/home.png"）。
btnTittle->setText(text)：这行代码直接调用QLabel的setText方法来更新文本内容。

至此，一个功能相对完整的自定义控件就封装好了。

三、控件的集成与事件处理

接下来，将这个自定义的PageSwitchButton控件集成到主界面的UI设计中，并为其添加鼠标点击事件的响应。

3.1 鼠标事件的重写

为了响应用户的点击操作，需要重写Qt的事件处理函数。对于鼠标单击，最常用的是mousePressEvent。

在pageswitchbutton.h中声明该事件处理函数。它是一个protected方法，因为这是Qt事件处理框架的约定。

cpp 复制代码

protected:
    void mousePressEvent(QMouseEvent *event);

然后在pageswitchbutton.cpp中提供其实现。在初期阶段，可以先用一个简单的打印输出来验证事件是否被成功捕获。

cpp 复制代码

#include <QDebug>

void PageSwitchButton::mousePressEvent(QMouseEvent *event)
{
    qDebug() << "PageSwitchButton is clicked";
    // 后面会在这里发射信号
}

当用户点击PageSwitchButton控件时，Qt的事件系统会自动调用这个函数，从而执行其中的代码。

在Qt Designer中设计的UI（.ui文件）默认只包含标准Qt控件。为了在UI中使用我们自定义的PageSwitchButton，需要使用"控件提升"功能。

在UI设计器中，从控件库拖拽一个占位控件到界面上，例如一个普通的QPushButton或QWidget。
右键点击这个占位控件，选择"提升为..."(Promote to...)。

在弹出的对话框中，输入自定义控件的类名PageSwitchButton。头文件名通常会自动填充。点击"添加"(Add)。

将新添加的PageSwitchButton类选中，然后点击"提升"(Promote)按钮。

操作完成后，可以看到对象查看器中，该控件的类型已经从原来的QPushButton变为了PageSwitchButton。

这个"提升"操作的本质是：它在.ui文件中记录了一个映射关系。当UI文件被uic（Qt UI Compiler）处理并生成C++代码时，uic会使用PageSwitchButton类来实例化这个控件，而不是原来的占位控件类。

四、编译与问题排查

在集成了自定义控件后，直接编译项目可能会遇到一些问题。

4.1 问题一：头文件找不到

首次编译可能会出现链接错误或元对象编译器（moc）错误。

这个错误提示表明moc在处理由.ui文件生成的ui_player.h时，无法找到pageswitchbutton.h。原因是moc默认只在系统的包含路径中查找头文件，而我们自定义的头文件位于项目源码目录中。

解决方案是在CMakeLists.txt文件中，明确告诉构建系统项目的源目录也是头文件搜索路径之一。

cmake 复制代码

INCLUDE_DIRECTORIES(
    ${PROJECT_SOURCE_DIR}
)

INCLUDE_DIRECTORIES是CMake命令，用于向编译器的头文件搜索路径列表中添加目录。${PROJECT_SOURCE_DIR}是CMake内置变量，指向项目的根源代码目录。

4.2 问题二：类型不匹配与继承关系修正

解决了头文件路径问题后，可能会遇到一个新的编译错误。

错误信息通常指出，在生成的UI代码中，试图调用一个PageSwitchButton对象上不存在的方法，例如setText。这是因为我们在UI设计器中使用的占位符是QPushButton，UI文件可能保留了一些QPushButton特有的属性设置。而我们自定义的PageSwitchButton最初继承自QWidget，QWidget本身没有setText方法。

虽然可以为PageSwitchButton手动添加一个setText方法，但这并非最佳方案。更根本的解决方案是调整继承关系。PageSwitchButton在功能和外观上都与按钮类似，将其基类从QWidget改为QPushButton会更合适。QPushButton本身就是QWidget的子类，它不仅包含了QWidget的所有功能，还增加了按钮相关的特性（如点击信号、样式等）。

修改步骤：

在pageswitchbutton.h中，将基类改为QPushButton。

在pageswitchbutton.cpp的构造函数初始化列表中，也同步修改。

完成修改后，再次编译运行，程序应该能正常启动。此时点击被提升的按钮，控制台会打印出我们在mousePressEvent中设置的调试信息。

五、样式美化与最终实现

基础功能实现后，需要对控件的外观进行精细调整，使其符合设计要求。

5.1 初始化按钮内容

在主窗口（例如Player类）的构造函数或初始化函数中，调用setImageAndText方法为按钮设置初始的图片和文本。

cpp 复制代码

// 在 Player 类的构造函数或初始化方法中
ui->homePageBtn->setImageAndText(":/images/homePage/shouyexuan.png", "我的");

此时运行程序，可以看到图片和文本已经显示出来，但外观可能不理想，比如带有QPushButton默认的边框和浮雕效果。

5.2 使用Qt样式表（QSS）进行美化

Qt强大的样式表系统（类似Web中的CSS）是进行UI美化的利器。我们在PageSwitchButton的构造函数中添加样式设置代码。

cpp 复制代码

// 在 PageSwitchButton 的构造函数中
// 1. 设置文本居中对齐
btnTittle->setAlignment(Qt::AlignCenter);

// 2. 去掉按钮的边框
setStyleSheet("border: none;");

setAlignment(Qt::AlignCenter)：QLabel的方法，用于设置其内容的对齐方式。Qt::AlignCenter表示水平和垂直都居中。
setStyleSheet("border: none;")：QWidget及其子类都有此方法。这里我们为整个PageSwitchButton（它现在是一个QPushButton）设置样式，将其边框去除。

此时，按钮的边框消失了，但文本颜色可能因为继承了父窗口或系统主题的样式而不够突出（例如，白色背景上的白色字体）。

我们需要明确指定文本颜色。可以在样式表中添加color属性。

cpp 复制代码

// 合并样式：同时设置文本颜色为黑色并去掉边框
setStyleSheet("color: black; border: none;");

再次运行，按钮的视觉效果就基本符合预期了。

5.3 应用到所有页面切换按钮

按照相同的步骤，将其余两个按钮也提升为PageSwitchButton类型。

然后在主窗口的初始化代码中，为所有按钮设置对应的图片和文本。

cpp 复制代码

// 在 player.cpp 中
ui->homePageBtn->setImageAndText(":/images/homePage/shouye.png", "首页");
ui->myPageBtn->setImageAndText(":/images/homePage/wode.png", "我的");
ui->sysPageBtn->setImageAndText(":/images/homePage/admin.png", "系统");

最终，导航栏的三个按钮都以统一且美观的样式呈现出来。

六、实现页面切换的核心逻辑：信号与槽

现在按钮的外观已经完成，核心任务是实现点击按钮切换右侧界面的功能。这通常通过Qt的QStackedWidget和信号槽机制来完成。

6.1 QStackedWidget简介

QStackedWidget是一个层叠窗口部件，可以容纳多个页面（子控件），但在同一时间只显示其中一个。通过索引（index）来控制当前显示哪个页面。

我们的目标是，将每个PageSwitchButton与QStackedWidget中的一个页面索引关联起来。

6.2 关联按钮与页面ID

为了建立这种关联，为PageSwitchButton类添加一个整型成员变量pageId。

在pageswitchbutton.h中声明：

cpp 复制代码

private:
    int pageId; // 存储与按钮关联的页面ID

并修改setImageAndText方法，增加一个pageId参数。

cpp 复制代码

public:
    void setImageAndText(const QString& imagePath, const QString& text, int pageId);

在pageswitchbutton.cpp中实现：

cpp 复制代码

void PageSwitchButton::setImageAndText(const QString &imagePath, const QString &text, int pageId)
{
    // ... 原有的图片和文本设置代码 ...
    btnImage->setPixmap(QPixmap(imagePath));
    btnTittle->setText(text);
    this->pageId = pageId; // 保存页面ID
}

现在，在主窗口初始化按钮时，可以传入对应的页面索引。

cpp 复制代码

// 在 player.cpp 中
ui->homePageBtn->setImageAndText(":/images/homePage/shouye.png", "首页", 0);
ui->myPageBtn->setImageAndText(":/images/homePage/wode.png", "我的", 1);
ui->sysPageBtn->setImageAndText(":/images/homePage/admin.png", "系统", 2);

6.3 定义并发送信号

当按钮被点击时，它需要通知主窗口。在Qt中，这种通信通过信号（signal）来完成。

在pageswitchbutton.h中，使用signals关键字声明一个信号。

cpp 复制代码

signals:
    void switchPage(int pageId);

信号是一个特殊的函数声明，它没有函数体。它的作用是作为事件发生的通知。

然后，在mousePressEvent中，使用emit关键字来发射这个信号。

cpp 复制代码

// 在 pageswitchbutton.cpp 中
void PageSwitchButton::mousePressEvent(QMouseEvent *event)
{
    emit switchPage(this->pageId); // 发射信号，并携带pageId
    QPushButton::mousePressEvent(event); // 调用基类的实现，确保按钮状态等正常
}

现在，每当PageSwitchButton被点击，它就会广播一个switchPage信号，并将自己的pageId作为参数传递出去。

6.4 定义槽函数并连接

主窗口（Player类）需要接收这个信号并做出响应。响应信号的函数称为槽（slot）。

在player.h中，使用private slots关键字声明一个槽函数。
cpp 复制代码
```
private slots:
    void onSwitchpage(int pageId); // 槽函数
```
在player.cpp中实现这个槽函数。它的逻辑很简单：获取传入的pageId，并设置QStackedWidget的当前索引。
cpp 复制代码
```
void Player::onSwitchpage(int pageId)
{
    ui->stackedWidget->setCurrentIndex(pageId); // 设置当前显示的页面
}
```

最后一步是建立信号和槽之间的连接。这个连接通常在主窗口的构造函数或一个专门的初始化函数中设置。

cpp 复制代码

// 在 Player::connectSigalAndSlot() 或构造函数中
connect(ui->homePageBtn, &PageSwitchButton::switchPage, this, &Player::onSwitchpage);
connect(ui->myPageBtn, &PageSwitchButton::switchPage, this, &Player::onSwitchpage);
connect(ui->sysPageBtn, &PageSwitchButton::switchPage, this, &Player::onSwitchpage);

connect函数的四个参数分别是：

信号发送者对象指针 (ui->homePageBtn)
指向信号的函数指针 (&PageSwitchButton::switchPage)
信号接收者对象指针 (this)
指向槽函数的函数指针 (&Player::onSwitchpage)

至此，完整的页面切换逻辑已经建立。运行程序，点击不同的按钮，可以看到右侧的QStackedWidget会相应地切换到不同的页面。

首页效果：

我的页面效果：

系统页面效果：

6.5 使用枚举类型优化

直接在代码中使用数字（0, 1, 2）被称为"魔术数字"，这会降低代码的可读性和可维护性。更好的做法是使用枚举类型。

在player.h中定义一个枚举：

cpp 复制代码

enum StackedWidgetPage
{
    HomePage,
    MyselfPage,
    AdminPage
};

然后用枚举成员替换代码中的硬编码数字。

cpp 复制代码

// 在 player.cpp 中
ui->homePageBtn->setImageAndText(":/images/homePage/shouye.png", "首页", HomePage);
ui->myPageBtn->setImageAndText(":/images/homePage/wode.png", "我的", MyselfPage);
ui->sysPageBtn->setImageAndText(":/images/homePage/admin.png", "系统", AdminPage);

这样做使得代码意图更加清晰。

七、实现动态高亮效果

为了提供更好的用户反馈，当一个按钮被选中时，它的外观（图片和文字）应该变为高亮状态，而其他按钮则应恢复为普通状态。

7.1 文本高亮功能

在PageSwitchButton类中添加一个新方法，用于动态改变文本的样式。

在pageswitchbutton.h中声明：

cpp 复制代码

void setTextColor(const QString& textColor);

在pageswitchbutton.cpp中实现，使用样式表来设置字体、大小、粗细和颜色：

cpp 复制代码

void PageSwitchButton::setTextColor(const QString &textColor)
{
    btnTittle->setStyleSheet("font-family: 微软雅黑;"
                             "font-size: 12px;"
                             "font-weight: bold;"
                             "color: " + textColor + ";");
}

在PageSwitchButton的构造函数中，可以设置一个默认的非高亮颜色，比如灰色。

cpp 复制代码

// 在 PageSwitchButton 构造函数中
setTextColor("#999999"); // 初始设置为灰色

当页面切换时，在主窗口的onSwitchpage槽函数中，需要将当前点击的按钮文本设置为高亮颜色（例如黑色）。

cpp 复制代码

// 伪代码，演示思路
// 在 onSwitchpage 中
// find the button clicked
// clickedButton->setTextColor("#000000"); // 设置为黑色

然而，这样做会导致一个问题：所有按钮的颜色都会被设置为高亮，因为onSwitchpage槽函数并不知道是哪个PageSwitchButton实例发出的信号。

正确的逻辑应该是：当一个页面被激活时，主窗口负责将所有按钮的状态进行重置，只高亮与当前页面对应的那个按钮。

7.2 状态重置与高亮逻辑

添加辅助函数 ：为了让主窗口能识别每个按钮，PageSwitchButton需要一个获取pageId的方法。

在pageswitchbutton.h中声明：
cpp 复制代码
```
int getPageId() const;
```
在pageswitchbutton.cpp中实现：
cpp 复制代码
```
int PageSwitchButton::getPageId() const
{
    return pageId;
}
```
创建重置函数 ：在主窗口类（Player）中，创建一个函数resetswitchBtnInfo，负责更新所有按钮的状态。

在player.h中声明：
cpp 复制代码
```
void resetswitchBtnInfo(int pageId);
```

实现重置逻辑 ：在player.cpp中实现resetswitchBtnInfo。

首先，需要找到窗口中所有的PageSwitchButton实例。可以使用findChildren<T*>()模板函数，它会遍历Player窗口的对象树，返回所有指定类型的子对象。
遍历所有按钮，如果按钮的pageId与当前激活的pageId不符，则将其文本颜色设置为非高亮（灰色）；如果相符，则设置为高亮（黑色）。（注意：这里的代码片段仅设置了非高亮，高亮在后续图片切换中隐式完成）。
根据激活的pageId，为每个按钮设置正确的图片（高亮版本或普通版本）。

为了更换图片，先在PageSwitchButton中添加一个只设置图片的函数。

在pageswitchbutton.h中：

cpp 复制代码

void setImage(const QString& imagePath);

在pageswitchbutton.cpp中：

cpp 复制代码

void PageSwitchButton::setImage(const QString &imagePath)
{
    btnImage->setPixmap(QPixmap(imagePath));
}

// 顺便优化setImageAndText
void PageSwitchButton::setImageAndText(const QString &imagePath, const QString &text, int pageId)
{
    setImage(imagePath);
    btnTittle->setText(text);
    this->pageId = pageId;
}

最终resetswitchBtnInfo的完整实现：

cpp 复制代码

void Player::resetswitchBtnInfo(int pageId)
{
    // 查找所有的PageSwitchButton
    QList<PageSwitchButton*> switchBtns = findChildren<PageSwitchButton*>();

    // 遍历并设置文本颜色
    for (auto switchBtn : switchBtns)
    {
        if (switchBtn->getPageId() == pageId) {
            switchBtn->setTextColor("#000000"); // 激活的按钮设为黑色
        } else {
            switchBtn->setTextColor("#999999"); // 未激活的设为灰色
        }
    }

    // 根据pageId设置图片
    if (pageId == HomePage)
    {
        ui->homePageBtn->setImage(":/images/homePage/shouyexuan.png");
        ui->myPageBtn->setImage(":/images/homePage/wode.png");
        ui->sysPageBtn->setImage(":/images/homePage/admin.png");
    }
    else if (pageId == MyselfPage)
    {
        ui->homePageBtn->setImage(":/images/homePage/shouye.png");
        ui->myPageBtn->setImage(":/images/homePage/wodexuan.png");
        ui->sysPageBtn->setImage(":/images/homePage/admin.png");
    }
    else if (pageId == AdminPage)
    {
        ui->homePageBtn->setImage(":/images/homePage/shouye.png");
        ui->myPageBtn->setImage(":/images/homePage/wode.png");
        ui->sysPageBtn->setImage(":/images/homePage/adminxuan.png");
    }
    else
    {
        qDebug() << "Unsupported page index";
    }
}

调用重置函数 ：在onSwitchpage槽函数中，切换页面后，立即调用resetswitchBtnInfo来更新所有按钮的状态。

cpp 复制代码

void Player::onSwitchpage(int pageId)
{
    ui->stackedWidget->setCurrentIndex(pageId);
    resetswitchBtnInfo(pageId); // 更新所有按钮状态
}

同时，在程序启动时，也应该调用一次该函数来设置初始状态。

cpp 复制代码

// 在 Player 构造函数中
// ... 其他初始化 ...
resetswitchBtnInfo(HomePage); // 设置初始高亮为主页按钮

经过以上步骤，一个功能完善、外观精美、交互友好的自定义页面切换按钮就完成了。它不仅实现了基本功能，还通过良好的封装和设计，具备了高可复用性和可维护性，是Qt GUI开发中一个典型的自定义控件实践。

C++基于微服务脚手架的视频点播系统---客户端（4）

Qt自定义控件：从零构建高级页面切换按钮

一、自定义控件的设计与基础搭建

1.1 项目文件结构

1.2 类定义与继承

1.3 控件内部组件的声明

1.4 控件内部布局与初始化

二、功能接口的封装与实现

2.1 接口函数的声明

2.2 接口函数的实现

三、控件的集成与事件处理

3.1 鼠标事件的重写

3.2 UI界面的控件提升（Widget Promotion）

四、编译与问题排查

4.1 问题一：头文件找不到

4.2 问题二：类型不匹配与继承关系修正

五、样式美化与最终实现

5.1 初始化按钮内容

5.2 使用Qt样式表（QSS）进行美化

5.3 应用到所有页面切换按钮

六、实现页面切换的核心逻辑：信号与槽

6.1 QStackedWidget简介

6.2 关联按钮与页面ID

6.3 定义并发送信号

6.4 定义槽函数并连接

6.5 使用枚举类型优化

七、实现动态高亮效果

7.1 文本高亮功能

7.2 状态重置与高亮逻辑