QScrollArea使用与悬浮滚动条#

在构造ChatRoom聊天项目的QT客户端界面时，我需要对联系人和聊天记录进行滚动查看处理，因此使用了QScrollArea来实现这一功能。

QScrollArea是QT中用于显示可滚动内容的组件，它可以包含一个子组件(QWidget)，并提供滚动条来查看子组件超出QScrollArea可视区域的部分。QScrollArea的界面结构如下：

QScrollArea
- QScrollBar
  - QWidget (子组件)
    - QVBoxLayout
      - Item(单个组件项)

QScrollArea的使用与自适应子组件宽度#

首先构建一个父QWidget用于存放这个QScrollArea，这样QScrollArea就会自动适配父QWidget的宽度。

随后，将QScrollArea和子组件QWidget的宽度都设置为Expanding，那么子组件就会与QScrollArea同步。

原生滚动条隐藏显示改变组件宽度的问题#

原生的QScrollArea并不会自动隐藏滚动条。因此需要重载原生的QScrollArea类，重新实现滚动条的隐藏和实现的逻辑。

但是，如果这样设计，会出现子组件QWidget的宽度在滚动条显示和隐藏时宽度发生闪烁。因为滚动条会占据QScrollArea内部可视区域的宽度，从而导致子组件的宽度也随之变化。

为了解决这个问题，我们可以自定义个QScrollBar类，作为QScrollArea的子组件，根据QT的Z-order机制，子组件会默认显示在父组件QScrollArea的上方。

并且将这个自定义的QScrollBar与QScrollArea的滚动条的事件连接，使自定义QScrollBar能够同步QScrollArea的滚动条位置和范围。

1
#ifndef CUSTOMSCROLLAREA_H
2
#define CUSTOMSCROLLAREA_H
3

4
#include <QScrollArea>
5
#include <QMouseEvent>
6
#include <QTimer>
7
#include <QPainter>
8
#include <QStyleOption>
9
#include <QResizeEvent>
10
/*
11
    自动隐藏滚动条的ScrollArea类
12
    当鼠标进入时显示滚动条，离开时隐藏滚动条。
13
*/
14
class CustomScrollArea : public QScrollArea
15
{
16
    Q_OBJECT
17

18
public:
19
    explicit CustomScrollArea(QWidget *parent = nullptr);
20

21
protected:
22
    // 鼠标进入和离开事件
23
    void enterEvent(QEnterEvent *event) override;
24
    void leaveEvent(QEvent *event) override;
25

26
protected slots:
27
    void showScrollBars();
28
    // 延迟隐藏滚动条
29
    void hideScrollBars();
30
    // 悬浮滚动条同步方法
31
    void onOverlayScrollBarValueChanged(int value);
32
    void onVerticalScrollBarValueChanged(int value);
33
    void updateOverlayScrollBarRange(int min, int max);
34

35
protected:
36
    // 计时器，用于延迟隐藏滚动条
37
    QTimer *hideTimer;
38
    bool isScrollBarVisible;
39
    // 悬浮滚动条
40
    QScrollBar* _overlayScrollBar;
41
};
42

43
#endif // CUSTOMSCROLLAREA_H

构造函数的实现：单独构造一个QScrollBar类，并设置为子类以及对应的样式表。QT的子类自动悬浮于父组件。

1
#include "CustomScrollArea.h"
2
#include <QScrollBar>
3

4
CustomScrollArea::CustomScrollArea(QWidget *parent)
5
    : QScrollArea(parent)
6
    , hideTimer(new QTimer(this))
7
    , isScrollBarVisible(false)
8
{
9
    // 初始隐藏滚动条
10
    setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
11
    setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
12

13
    // 子组件，默认悬浮出现
14
    _overlayScrollBar = new QScrollBar(Qt::Vertical, this);
15
    _overlayScrollBar->setStyleSheet(R"(
16
        QScrollBar:vertical {
17
            background: transparent;
18
            width: 8px;
19
            border-radius: 4px;
20
            margin: 0px;
21
        }
22
        QScrollBar::handle:vertical {
23
            background: rgba(0, 0, 0, 0.3);
24
            border-radius: 4px;
25
            min-height: 20px;
26
        }
27
        QScrollBar::handle:vertical:hover {
28
            background: rgba(0, 0, 0, 0.5);
29
        }
30
        QScrollBar::add-line:vertical,
31
        QScrollBar::sub-line:vertical {
32
            border: none;
33
            background: none;
34
            height: 0px;
35
            subcontrol-position: bottom;
36
            subcontrol-origin: margin;
37
        }
38
        QScrollBar::add-page:vertical,
39
        QScrollBar::sub-page:vertical {
40
            background: none;
41
        }
42
    )");
43

44
    // 初始隐藏悬浮滚动条
45
    _overlayScrollBar->hide();
46

47
    // 连接信号进行同步(滚动条位置，范围)
48
    // 直接操作自定义滚动条，同步原生滚动条
49
    connect(_overlayScrollBar, &QScrollBar::valueChanged,
50
            this, &CustomScrollArea::onOverlayScrollBarValueChanged);
51
    // QScrollArea原生滚动条滚动，同步自定义滚动条
52
    connect(verticalScrollBar(), &QScrollBar::valueChanged,
53
            this, &CustomScrollArea::onVerticalScrollBarValueChanged);
54
    // 原生滚动条范围改变，同步自定义滚动条范围。
55
    connect(verticalScrollBar(), &QScrollBar::rangeChanged,
56
            this, &CustomScrollArea::updateOverlayScrollBarRange);
57

58
    // 确保内容可以自适应大小
59
    setWidgetResizable(true);
60

61
    // 设置定时器
62
    hideTimer->setSingleShot(true);
63
    hideTimer->setInterval(500); // 默认500毫秒后隐藏
64
    // 定时器超时，隐藏滚动条
65
    connect(hideTimer, &QTimer::timeout, this, &CustomScrollArea::hideScrollBars);
66
    // 启用鼠标跟踪
67
    setMouseTracking(true);
68
}

悬浮滚动条的显示和隐藏事件，以及对应的槽函数。

当鼠标进入范围，直接显示滚动条，重置定时器。
当鼠标离开范围，使用定时器来延迟隐藏滚动条，当计时器超时后，隐藏滚动条。

1
void CustomScrollArea::enterEvent(QEnterEvent *event)
2
{
3
    showScrollBars();
4
    QScrollArea::enterEvent(event);
5
}
6

7
void CustomScrollArea::leaveEvent(QEvent *event)
8
{
9
    // 延迟隐藏滚动条
10
    hideTimer->start();
11
    QScrollArea::leaveEvent(event);
12
}
13

14
void CustomScrollArea::showScrollBars()
15
{
16
    if (!isScrollBarVisible) {
17
        _overlayScrollBar->show();
18
        // 设置悬浮滚动条的位置和大小
19
        _overlayScrollBar->setGeometry(width() - 8, 0, 8, height());
20
        // 同步滚动条范围和值
21
        updateOverlayScrollBarRange(verticalScrollBar()->minimum(), verticalScrollBar()->maximum());
22
        _overlayScrollBar->setValue(verticalScrollBar()->value());
23
        isScrollBarVisible = true;
24
    }
25
    hideTimer->stop();
26
}
27

28
void CustomScrollArea::hideScrollBars()
29
{
30
    if (_overlayScrollBar) {
31
        _overlayScrollBar->hide();
32
    }
33
    isScrollBarVisible = false;
34
}

编写关于滚动条值和范围的槽函数，同步悬浮滚动条和原生滚动条的状态。

使用blockSignals(true)和blockSignals(false)来防止无限递归调用。

1
void CustomScrollArea::onOverlayScrollBarValueChanged(int value)
2
{
3
    // 防止无限递归，触发值改变事件
4
    verticalScrollBar()->blockSignals(true);
5
    verticalScrollBar()->setValue(value);
6
    verticalScrollBar()->blockSignals(false);
7
}
8

9
void CustomScrollArea::onVerticalScrollBarValueChanged(int value)
10
{
11
    // 防止无限递归，触发值改变事件
12
    _overlayScrollBar->blockSignals(true);
13
    _overlayScrollBar->setValue(value);
14
    _overlayScrollBar->blockSignals(false);
15
}
16

17
void CustomScrollArea::updateOverlayScrollBarRange(int min, int max)
18
{
19
    _overlayScrollBar->setRange(min, max);
20
    _overlayScrollBar->setPageStep(verticalScrollBar()->pageStep());
21
    _overlayScrollBar->setSingleStep(verticalScrollBar()->singleStep());
22
}