Qt 图片浏览器控件开发：从编译错误到高清适配的完整实践

Qt图片浏览器控件开发实践

原创于 2025-11-17 19:05:08 发布 · 775 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#qt #开发语言

前言

在 Qt 项目开发中，图片浏览器是常见需求，核心要解决高效加载、清晰显示、适配窗口三大问题。本文将详细记录一个支持懒加载、高清缩放、双击预览的图片浏览器控件开发过程，包括遇到的编译 / 链接错误、原因分析、解决方案，以及最终优化效果，适合 Qt 开发者参考学习。

一、控件核心功能

最终实现的 ImageViewerWidget 控件具备以下功能：

文件夹图片扫描；
并发懒加载（避免一次性加载过多图片卡顿）；
网格布局显示（支持自定义每行图片数）；
高清缩放（从原图适配尺寸，无模糊）；
双击预览（支持最大化、滚轮缩放、自动居中）；
窗口自适应（窗口缩放时图片自动适配尺寸）。

二、开发过程中的关键错误与解决方案

（一）编译错误：成员函数 / 变量未定义 / 不匹配

1. 错误示例 1：`error C2039: "original": 不是 "ImageViewerWidget::ImageLabelData" 的成员`

原因：结构体 ImageLabelData 中定义的成员名是 originalPix，但代码中误写为 original，变量名拼写不一致。
解决方案：统一变量名，确保所有引用处与结构体定义一致。

// 结构体定义（正确）
struct ImageLabelData {
    QPixmap originalPix; // 成员名：originalPix
    QPixmap thumbnail;
    QLabel* label;
    // 其他成员...
};

// 错误引用（需修正）
QPixmap fitPixmap = labelData.original.scaled(...); // 错误：original 不存在
// 正确引用
QPixmap fitPixmap = labelData.originalPix.scaled(...); // 匹配结构体成员名

2. 错误示例 2：`error C2039: "mapToWidget": 不是 "QScrollArea" 的成员`

原因：mapToWidget 是 QWidget 的成员函数，QScrollArea 没有该方法，误将滚动区域当作普通部件调用。
解决方案：通过 QScrollArea::widget() 获取滚动区域的子部件，再调用坐标转换方法。

// 错误代码
QPoint viewportTopLeft = m_scrollArea->mapToWidget(viewportRect.topLeft());
// 正确代码
QWidget* scrollWidget = m_scrollArea->widget();
QPoint viewportTopLeft = scrollWidget->mapFromParent(viewportRect.topLeft());

3. 错误示例 3：`error C2039: "relockForWrite": 不是 "QWriteLocker" 的成员`

原因：relockForWrite 是 Qt 5.15+ 新增方法，项目使用的 Qt 5.14.2 不支持。
解决方案：通过重新创建 QWriteLocker 对象实现重锁（Qt 5.14 兼容方案）。

// 错误代码（Qt 5.15+ 支持）
uiLocker.relockForWrite();
// 正确代码（Qt 5.14 兼容）
QWriteLocker uiLocker2(&m_uiLock); // 重新创建锁对象，自动加锁
// 执行写操作...
uiLocker2.unlock(); // 可选，超出作用域自动释放

（二）链接错误：无法解析的外部符号

1. 错误示例：`LNK2019: 无法解析的外部符号 "public: void __cdecl ImageViewerWidget::setImageFolder(class QString const &)"`

原因：头文件声明了函数，但源文件中未实现，或函数签名不一致（返回值、参数类型、const 修饰等）。
解决方案：
1. 确保所有头文件声明的函数在源文件中都有实现；
2. 严格保持函数签名一致（包括 const、引用符号 & 等）；
3. 检查 .pro 文件（qmake）或项目配置，确保源文件已添加到编译列表。

// 头文件声明
void setImageFolder(const QString& path);

// 源文件实现（签名必须完全一致）
void ImageViewerWidget::setImageFolder(const QString &path) {
    QWriteLocker uiLocker(&m_uiLock);
    m_imageFolder = path;
    // 文件夹存在性检查、刷新图片等逻辑...
}

2. 常见链接错误汇总及排查步骤

错误类型	核心原因	排查步骤
LNK2001	虚函数仅声明未实现	检查 `resizeEvent`、`eventFilter` 等虚函数是否有实现
LNK2019	普通函数 / 槽函数未实现	1. 确认源文件有对应实现；2. 函数签名与声明一致；3. 源文件已加入项目
LNK1120	多个外部符号未解析	先解决所有 LNK2001/LNK2019 错误，通常是连锁反应

（三）功能错误：图片模糊、显示过小

1. 问题 1：网格图片模糊

原因：直接放大低分辨率缩略图，未使用原图重新缩放。
解决方案：
1. 加载时保存原图（QImage 加载，无压缩）；
2. 窗口 / 标签尺寸变化时，从原图重新缩放适配（使用 Qt::SmoothTransformation 高质量缩放）。

// 异步加载任务中保存原图
void ImageLoadTask::run() {
    ImageLoadTaskResult result;
    // 用 QImage 加载原图（保留完整像素信息）
    QImage originalImage(m_imgPath);
    if (originalImage.isNull()) {
        result.success = false;
        emit taskFinished(result);
        return;
    }
    // 缩略图从原图缩放（高质量）
    QImage thumbnailImage = originalImage.scaled(
        m_thumbnailWidth, m_thumbnailHeight,
        Qt::KeepAspectRatio,
        Qt::SmoothTransformation
    );
    // 保存原图和缩略图
    result.originalPix = QPixmap::fromImage(originalImage);
    result.thumbnail = QPixmap::fromImage(thumbnailImage);
    result.success = true;
    emit taskFinished(result);
}

// 标签尺寸变化时从原图重新适配
void ImageViewerWidget::delayedResizeThumbnails() {
    QReadLocker uiLocker(&m_uiLock);
    for (int index : visibleIndices) {
        auto& labelData = m_imageLabelList[index];
        if (labelData.isLoaded && labelData.label) {
            QPixmap fitPixmap = labelData.originalPix.scaled(
                labelData.label->size() - QSize(10, 10), // 10px 内边距
                Qt::KeepAspectRatio,
                Qt::SmoothTransformation // 高质量缩放
            );
            labelData.label->setPixmap(fitPixmap);
        }
    }
}

2. 问题 2：预览图过小、不适配窗口

原因：预览窗口初始尺寸限制过严，未支持最大化和窗口自适应。
解决方案：
1. 取消预览窗口最大尺寸限制，增加最大化按钮；
2. 初始尺寸按屏幕 90% 适配；
3. 窗口缩放时自动调整图片尺寸。

ImagePreviewDialog::ImagePreviewDialog(const QPixmap& originalPix, QWidget* parent)
    : QDialog(parent)
    , m_originalPix(originalPix)
{
    setWindowTitle("图片预览");
    setMinimumSize(800, 600); // 基础最小尺寸
    setMaximumSize(QWIDGETSIZE_MAX, QWIDGETSIZE_MAX); // 取消最大尺寸限制
    setWindowFlags(windowFlags() | Qt::WindowMaximizeButtonHint); // 增加最大化按钮
    setAttribute(Qt::WA_DeleteOnClose);

    m_scrollArea = new QScrollArea(this);
    m_scrollArea->setWidgetResizable(true); // 滚动区域自适应窗口

    // 初始尺寸按屏幕 90% 适配
    QSize screenSize = QApplication::desktop()->availableGeometry().size() * 0.9;
    QSize initSize = originalPix.size().scaled(screenSize, Qt::KeepAspectRatio);
    m_imageLabel->setPixmap(originalPix.scaled(initSize, Qt::KeepAspectRatio, Qt::SmoothTransformation));

    // 其他布局初始化...
}

// 窗口缩放时自动适配
void ImagePreviewDialog::resizeEvent(QResizeEvent* event) {
    Q_UNUSED(event);
    if (m_originalPix.isNull()) return;

    QMutexLocker locker(&m_scaleMutex);
    QSize viewportSize = m_scrollArea->viewport()->size();
    QSize scaledSize = m_originalPix.size() * m_scaleFactor;

    // 图片小于窗口时，自动放大到窗口大小（最大 2 倍原图）
    if (scaledSize.width() < viewportSize.width() && scaledSize.height() < viewportSize.height()) {
        double scaleX = (double)viewportSize.width() / m_originalPix.width();
        double scaleY = (double)viewportSize.height() / m_originalPix.height();
        m_scaleFactor = qMin(qMin(scaleX, scaleY), 2.0);
        scaledSize = m_originalPix.size() * m_scaleFactor;
    }

    m_imageLabel->setPixmap(m_originalPix.scaled(scaledSize, Qt::KeepAspectRatio, Qt::SmoothTransformation));
}

三、完整代码实现

（一）头文件 `ImageViewerWidget.h`

#ifndef IMAGEVIEWERWIDGET_H
#define IMAGEVIEWERWIDGET_H

#include <QWidget>
#include <QVBoxLayout>
#include <QGridLayout>
#include <QLabel>
#include <QTimer>
#include <QDir>
#include <QFileInfoList>
#include <QStringList>
#include <QPixmap>
#include <QEvent>
#include <QDialog>
#include <QMouseEvent>
#include <QWheelEvent>
#include <QMessageBox>
#include <QScrollArea>
#include <QThreadPool>
#include <QRunnable>
#include <QMutex>
#include <QObject>
#include <QElapsedTimer>
#include <QtMath>
#include <QSemaphore>
#include <QMetaType>
#include <QScrollBar>
#include <QReadWriteLock>

class ImageLoadTask;
// 图片加载结果结构体
struct ImageLoadTaskResult {
    QString imgPath;
    QPixmap thumbnail;
    QPixmap originalPix; // 原图
    bool success = false;
    int index = -1;
};

// 图片预览对话框
class ImagePreviewDialog : public QDialog
{
    Q_OBJECT
public:
    explicit ImagePreviewDialog(const QPixmap& originalPix, QWidget* parent = nullptr);
    ~ImagePreviewDialog() override = default;

protected:
    void wheelEvent(QWheelEvent* event) override;
    void resizeEvent(QResizeEvent* event) override;

private:
    void scaleImage(double factor);
    QLabel* m_imageLabel;
    QScrollArea* m_scrollArea;
    QPixmap m_originalPix;
    double m_scaleFactor = 1.0;
    const double m_minScale = 0.5; // 最小缩放比例（50%）
    const double m_maxScale = 20.0; // 最大缩放比例（20倍）
    QMutex m_scaleMutex;
};

// 图片加载线程任务
class ImageLoadTask : public QObject, public QRunnable
{
    Q_OBJECT
public:
    ImageLoadTask(const QString& imgPath, int thumbnailWidth, int thumbnailHeight, int index, QObject* receiver, QObject* parent = nullptr);
    void run() override;

signals:
    void taskFinished(const ImageLoadTaskResult& result);

private:
    QString m_imgPath;
    int m_thumbnailWidth;
    int m_thumbnailHeight;
    int m_index;
    QObject* m_receiver;
};

// 主图片浏览器控件
class ImageViewerWidget : public QWidget
{
    Q_OBJECT

public:
    explicit ImageViewerWidget(QWidget* parent = nullptr);
    ~ImageViewerWidget() override;

    // 公有接口
    void setImageFolder(const QString& path); // 设置图片文件夹
    void setRefreshInterval(int interval = 5000); // 设置自动刷新间隔（ms）
    void setImagesPerRow(int count = 2); // 设置每行显示图片数
    void setMaxImageCount(int count = 100); // 设置最大加载图片数
    void setMaxConcurrentLoads(int count = 8); // 设置最大并发加载数
    void setLazyLoad(bool enable = true); // 启用/禁用懒加载

protected:
    void resizeEvent(QResizeEvent* event) override;
    void showEvent(QShowEvent* event) override;
    void scrollContentsBy(int dx, int dy);

private slots:
    void refreshImages(); // 刷新图片列表
    void adjustThumbnailSizeByWindow(); // 适配窗口调整缩略图尺寸
    void onTaskFinished(const ImageLoadTaskResult& result); // 加载任务完成回调
    void delayedResizeThumbnails(); // 延迟调整缩略图尺寸（避免频繁触发）
    void batchUpdateUI(); // 批量更新UI（避免频繁刷新）
    void checkVisibleImages(); // 检查可视区域图片，触发懒加载

private:
    // 图片标签数据结构
    struct ImageLabelData {
        QPixmap originalPix; // 原图
        QPixmap thumbnail; // 缩略图
        QLabel* label; // 显示标签
        QString imgPath; // 图片路径
        bool isLoaded = false; // 是否已加载
        bool isLoading = false; // 是否正在加载
        bool isVisible = false; // 是否可视
        int index = -1; // 索引
    };

    QStringList loadPngImages(); // 扫描文件夹中的PNG图片
    QLabel* createThumbnailLabel(const QString& imgPath, ImageLabelData& data, int index); // 创建图片标签
    void resetGridLayoutStretch(); // 重置布局拉伸比例
    bool eventFilter(QObject *watched, QEvent *event) override; // 事件过滤器（监听双击）
    QList<int> getVisibleImageIndices(); // 获取可视区域图片索引
    void startLoadTasks(const QList<int>& indices); // 启动图片加载任务
    
    void cancelAllLoadTasks(); // 取消所有加载任务
    void cancelAllLoadTasksUnlocked(); // 无锁版本（内部调用）

private:
    QString m_imageFolder; // 图片文件夹路径
    int m_refreshInterval; // 自动刷新间隔
    int m_imagesPerRow; // 每行图片数
    int m_thumbnailWidth = 400; // 缩略图宽度
    int m_thumbnailHeight = 400; // 缩略图高度
    int m_maxImageCount = 100; // 最大加载图片数
    int m_maxConcurrentLoads = 8; // 最大并发加载数
    bool m_enableLazyLoad = true; // 是否启用懒加载

    // 定时器
    QTimer* m_refreshTimer; // 自动刷新定时器
    QTimer* m_resizeTimer; // 窗口缩放延迟定时器
    QTimer* m_batchUpdateTimer; // 批量UI更新定时器
    QTimer* m_lazyLoadTimer; // 懒加载检查定时器

    // 布局
    QVBoxLayout* m_mainLayout; // 主布局
    QGridLayout* m_imageLayout; // 图片网格布局

    QStringList m_lastImagePaths; // 上次扫描的图片路径列表
    QList<ImageLabelData> m_imageLabelList; // 图片标签列表
    QScrollArea* m_scrollArea; // 滚动区域
    QWidget* m_scrollContentWidget; // 滚动区域子部件
    QThreadPool* m_threadPool; // 线程池（用于并发加载）

    // 线程安全锁
    QReadWriteLock m_taskLock; // 任务锁
    QReadWriteLock m_uiLock; // UI锁
    QSemaphore m_loadSemaphore; // 并发加载信号量

    QList<ImageLoadTask*> m_runningTasks; // 正在运行的加载任务
    QList<ImageLoadTaskResult> m_pendingResults; // 待更新的加载结果
    bool m_isRefreshing = false; // 是否正在刷新
};

Q_DECLARE_METATYPE(ImageLoadTaskResult)

#endif // IMAGEVIEWERWIDGET_H

（二）源文件 `ImageViewerWidget.cpp`

#include "ImageViewerWidget.h"
#include <QDebug>
#include <QFile>
#include <QPainter>
#include <QPushButton>
#include <QHBoxLayout>
#include <QApplication>
#include <QCoreApplication>
#include <QDesktopWidget>

// ------------------------------ ImagePreviewDialog 实现 ------------------------------
ImagePreviewDialog::ImagePreviewDialog(const QPixmap& originalPix, QWidget* parent)
    : QDialog(parent)
    , m_originalPix(originalPix)
{
    setWindowTitle("图片预览");
    setMinimumSize(800, 600);
    setMaximumSize(QWIDGETSIZE_MAX, QWIDGETSIZE_MAX);
    setWindowFlags(windowFlags() | Qt::WindowMaximizeButtonHint);
    setAttribute(Qt::WA_DeleteOnClose);

    m_scrollArea = new QScrollArea(this);
    m_scrollArea->setWidgetResizable(true);
    m_scrollArea->setBackgroundRole(QPalette::Dark);
    m_scrollArea->setHorizontalScrollBarPolicy(Qt::ScrollBarAsNeeded);
    m_scrollArea->setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);

    m_imageLabel = new QLabel(this);
    m_imageLabel->setAlignment(Qt::AlignCenter);
    m_imageLabel->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);

    // 初始尺寸适配屏幕90%
    QSize screenSize = QApplication::desktop()->availableGeometry().size() * 0.9;
    QSize initSize = originalPix.size().scaled(screenSize, Qt::KeepAspectRatio);
    m_imageLabel->setPixmap(originalPix.scaled(initSize, Qt::KeepAspectRatio, Qt::SmoothTransformation));

    m_scrollArea->setWidget(m_imageLabel);

    QVBoxLayout* layout = new QVBoxLayout(this);
    layout->addWidget(m_scrollArea);
    layout->setContentsMargins(0, 0, 0, 0);

    resize(initSize);
}

// 滚轮缩放
void ImagePreviewDialog::wheelEvent(QWheelEvent* event)
{
    QMutexLocker locker(&m_scaleMutex);
    double delta = event->angleDelta().y() / 120.0;
    double factor = (delta > 0) ? 1.2 : 0.8; // 缩放速度
    scaleImage(factor);
}

// 窗口缩放适配
void ImagePreviewDialog::resizeEvent(QResizeEvent* event)
{
    Q_UNUSED(event);
    if (m_originalPix.isNull()) return;

    QMutexLocker locker(&m_scaleMutex);
    QSize viewportSize = m_scrollArea->viewport()->size();
    QSize scaledSize = m_originalPix.size() * m_scaleFactor;

    if (scaledSize.width() < viewportSize.width() && scaledSize.height() < viewportSize.height()) {
        double scaleX = (double)viewportSize.width() / m_originalPix.width();
        double scaleY = (double)viewportSize.height() / m_originalPix.height();
        m_scaleFactor = qMin(qMin(scaleX, scaleY), 2.0);
        scaledSize = m_originalPix.size() * m_scaleFactor;
    }

    m_imageLabel->setPixmap(m_originalPix.scaled(scaledSize, Qt::KeepAspectRatio, Qt::SmoothTransformation));
}

// 缩放图片
void ImagePreviewDialog::scaleImage(double factor)
{
    m_scaleFactor *= factor;
    m_scaleFactor = qBound(m_minScale, m_scaleFactor, m_maxScale);

    QSize scaledSize = m_originalPix.size() * m_scaleFactor;
    m_imageLabel->setPixmap(m_originalPix.scaled(scaledSize, Qt::KeepAspectRatio, Qt::SmoothTransformation));
    m_imageLabel->resize(scaledSize);

    // 缩放后居中
    QScrollBar* hBar = m_scrollArea->horizontalScrollBar();
    QScrollBar* vBar = m_scrollArea->verticalScrollBar();
    hBar->setValue((scaledSize.width() - m_scrollArea->viewport()->width()) / 2);
    vBar->setValue((scaledSize.height() - m_scrollArea->viewport()->height()) / 2);
}

// ------------------------------ ImageLoadTask 实现 ------------------------------
ImageLoadTask::ImageLoadTask(const QString& imgPath, int thumbnailWidth, int thumbnailHeight, int index, QObject* receiver, QObject* parent)
    : QObject(parent)
    , QRunnable()
    , m_imgPath(imgPath)
    , m_thumbnailWidth(thumbnailWidth)
    , m_thumbnailHeight(thumbnailHeight)
    , m_index(index)
    , m_receiver(receiver)
{
    setAutoDelete(false);
}

// 线程运行函数：加载图片
void ImageLoadTask::run()
{
    ImageLoadTaskResult result;
    result.imgPath = m_imgPath;
    result.index = m_index;

    // 用QImage加载原图（保留完整像素）
    QImage originalImage(m_imgPath);
    if (originalImage.isNull()) {
        qWarning() << "[ImageLoadTask] 图片读取失败：" << m_imgPath;
        result.success = false;
        emit taskFinished(result);
        return;
    }

    // 生成高质量缩略图
    QImage thumbnailImage = originalImage.scaled(
        m_thumbnailWidth, m_thumbnailHeight,
        Qt::KeepAspectRatio,
        Qt::SmoothTransformation
    );

    result.originalPix = QPixmap::fromImage(originalImage);
    result.thumbnail = QPixmap::fromImage(thumbnailImage);
    result.success = true;

    emit taskFinished(result);
}

// ------------------------------ ImageViewerWidget 实现 ------------------------------
ImageViewerWidget::ImageViewerWidget(QWidget *parent)
    : QWidget(parent)
    , m_refreshInterval(5000)
    , m_imagesPerRow(2)
    , m_maxImageCount(100)
    , m_maxConcurrentLoads(8)
    , m_enableLazyLoad(true)
    , m_loadSemaphore(m_maxConcurrentLoads)
{
    qRegisterMetaType<ImageLoadTaskResult>("ImageLoadTaskResult");
    qRegisterMetaType<ImageLoadTaskResult>("const ImageLoadTaskResult&");

    // 初始化主布局
    m_mainLayout = new QVBoxLayout(this);
    m_mainLayout->setContentsMargins(10, 10, 10, 10);
    m_mainLayout->setSpacing(0);

    // 初始化滚动区域
    m_scrollArea = new QScrollArea(this);
    m_scrollArea->setWidgetResizable(true);
    m_scrollArea->setStyleSheet("QScrollArea{border: none;}");
    m_scrollArea->setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);
    m_scrollArea->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
    m_scrollArea->verticalScrollBar()->setStyleSheet("QScrollBar{border: none; background: transparent; width: 8px;}");

    // 滚动区域子部件（图片容器）
    m_scrollContentWidget = new QWidget(m_scrollArea);
    m_scrollContentWidget->setStyleSheet("background-color: #f5f5f5;");
    m_imageLayout = new QGridLayout(m_scrollContentWidget);
    m_imageLayout->setContentsMargins(10, 10, 10, 10);
    m_imageLayout->setSpacing(15);
    resetGridLayoutStretch();

    m_scrollArea->setWidget(m_scrollContentWidget);
    m_mainLayout->addWidget(m_scrollArea);

    // 初始化定时器
    m_batchUpdateTimer = new QTimer(this);
    m_batchUpdateTimer->setInterval(10);
    connect(m_batchUpdateTimer, &QTimer::timeout, this, &ImageViewerWidget::batchUpdateUI);
    m_batchUpdateTimer->start();

    m_lazyLoadTimer = new QTimer(this);
    m_lazyLoadTimer->setInterval(50);
    connect(m_lazyLoadTimer, &QTimer::timeout, this, &ImageViewerWidget::checkVisibleImages);
    m_lazyLoadTimer->start();

    m_refreshTimer = new QTimer(this);
    m_refreshTimer->setInterval(m_refreshInterval);
    connect(m_refreshTimer, &QTimer::timeout, this, &ImageViewerWidget::refreshImages);

    m_resizeTimer = new QTimer(this);
    m_resizeTimer->setSingleShot(true);
    m_resizeTimer->setInterval(200);
    connect(m_resizeTimer, &QTimer::timeout, this, &ImageViewerWidget::delayedResizeThumbnails);

    // 初始化线程池
    m_threadPool = QThreadPool::globalInstance();
    m_threadPool->setMaxThreadCount(m_maxConcurrentLoads);
    m_threadPool->setExpiryTimeout(-1);

    // 滚动时检查懒加载
    connect(m_scrollArea->verticalScrollBar(), &QScrollBar::valueChanged, this, [this]() {
        if (m_enableLazyLoad) {
            m_lazyLoadTimer->start(50);
        }
    });
}

// 析构函数：释放资源
ImageViewerWidget::~ImageViewerWidget()
{
    m_refreshTimer->stop();
    m_resizeTimer->stop();
    m_batchUpdateTimer->stop();
    m_lazyLoadTimer->stop();

    cancelAllLoadTasks();
    m_threadPool->waitForDone(1000);

    // 释放UI资源
    QWriteLocker uiLocker(&m_uiLock);
    while (m_imageLayout->count() > 0) {
        QLayoutItem* item = m_imageLayout->takeAt(0);
        QLabel* label = qobject_cast<QLabel*>(item->widget());
        if (label) {
            label->removeEventFilter(this);
            label->deleteLater();
        }
        delete item;
    }
    m_imageLabelList.clear();
    m_pendingResults.clear();

    // 释放任务资源
    QWriteLocker taskLocker(&m_taskLock);
    qDeleteAll(m_runningTasks);
    m_runningTasks.clear();
}

// 窗口缩放事件
void ImageViewerWidget::resizeEvent(QResizeEvent* event)
{
    QWidget::resizeEvent(event);
    m_resizeTimer->start(200); // 延迟触发，避免频繁调整
}

// 窗口显示事件
void ImageViewerWidget::showEvent(QShowEvent* event)
{
    QWidget::showEvent(event);
    if (m_enableLazyLoad && !m_imageLabelList.isEmpty()) {
        checkVisibleImages();
    }
}

// 滚动内容调整
void ImageViewerWidget::scrollContentsBy(int dx, int dy)
{
    m_scrollArea->widget()->scroll(dx, dy);
    if (m_enableLazyLoad) {
        m_lazyLoadTimer->start(50);
    }
}

// 获取可视区域图片索引
QList<int> ImageViewerWidget::getVisibleImageIndices()
{
    QReadLocker uiLocker(&m_uiLock);
    QList<int> visibleIndices;
    if (m_imageLabelList.isEmpty()) return visibleIndices;

    QRect viewportRect = m_scrollArea->viewport()->rect();
    QWidget* scrollWidget = m_scrollArea->widget();
    if (!scrollWidget) return visibleIndices;
    QPoint viewportTopLeft = scrollWidget->mapFromParent(viewportRect.topLeft());

    for (const auto& labelData : m_imageLabelList) {
        if (!labelData.label) continue;
        QRect labelRect = labelData.label->geometry();
        labelRect.translate(0, -m_thumbnailHeight); // 扩大检测范围，提前加载
        labelRect.setHeight(labelRect.height() + 2 * m_thumbnailHeight);
        if (labelRect.intersects(viewportRect.translated(viewportTopLeft))) {
            visibleIndices.append(labelData.index);
        }
    }

    return visibleIndices;
}

// 检查可视区域图片，触发懒加载
void ImageViewerWidget::checkVisibleImages()
{
    if (!m_enableLazyLoad || m_isRefreshing || m_imageLabelList.isEmpty()) return;

    QList<int> visibleIndices = getVisibleImageIndices();
    if (visibleIndices.isEmpty()) return;

    startLoadTasks(visibleIndices);
}

// 启动图片加载任务
void ImageViewerWidget::startLoadTasks(const QList<int>& indices)
{
    QWriteLocker taskLocker(&m_taskLock);
    QReadLocker uiLocker(&m_uiLock);

    for (int index : indices) {
        if (index < 0 || index >= m_imageLabelList.size()) continue;
        auto& labelData = m_imageLabelList[index];
        if (labelData.isLoaded || labelData.isLoading) continue;

        labelData.isLoading = true;

        // 信号量控制并发数
        if (!m_loadSemaphore.tryAcquire(1, 100)) {
            labelData.isLoading = false;
            continue;
        }

        // 创建加载任务
        ImageLoadTask* task = new ImageLoadTask(
            labelData.imgPath,
            m_thumbnailWidth,
            m_thumbnailHeight,
            index,
            this,
            this
        );
        connect(task, &ImageLoadTask::taskFinished, this, &ImageViewerWidget::onTaskFinished, Qt::QueuedConnection);
        m_runningTasks.append(task);
        m_threadPool->start(task);
    }
}

// 加载任务完成回调
void ImageViewerWidget::onTaskFinished(const ImageLoadTaskResult& result)
{
    m_loadSemaphore.release(1); // 释放信号量

    if (!result.success) {
        qWarning() << "[ImageViewer] 加载图片失败：" << result.imgPath;
        return;
    }

    // 加入待更新队列
    QWriteLocker uiLocker(&m_uiLock);
    m_pendingResults.append(result);
}

// 批量更新UI
void ImageViewerWidget::batchUpdateUI()
{
    if (m_pendingResults.isEmpty()) return;

    QWriteLocker uiLocker(&m_uiLock);
    if (m_pendingResults.isEmpty()) return;

    for (const auto& result : m_pendingResults) {
        if (result.index < 0 || result.index >= m_imageLabelList.size()) continue;
        auto& labelData = m_imageLabelList[result.index];
        if (labelData.imgPath != result.imgPath) continue;

        // 更新图片数据
        labelData.originalPix = result.originalPix;
        labelData.thumbnail = result.thumbnail;
        labelData.isLoaded = true;
        labelData.isLoading = false;

        // 从原图适配标签尺寸，保证清晰
        if (labelData.label) {
            QPixmap fitPixmap = result.originalPix.scaled(
                labelData.label->size() - QSize(10, 10),
                Qt::KeepAspectRatio,
                Qt::SmoothTransformation
            );
            labelData.label->setPixmap(fitPixmap);
            labelData.label->setText(""); // 清除加载提示
            labelData.label->update();
        }
    }

    m_pendingResults.clear();
}

// 延迟调整缩略图尺寸
void ImageViewerWidget::delayedResizeThumbnails()
{
    QReadLocker uiLocker(&m_uiLock);
    if (m_imageLabelList.isEmpty()) return;

    QList<int> visibleIndices = getVisibleImageIndices();
    for (int index : visibleIndices) {
        if (index < 0 || index >= m_imageLabelList.size()) continue;
        auto& labelData = m_imageLabelList[index];
        if (labelData.isLoaded && labelData.label) {
            // 从原图重新适配，避免模糊
            QPixmap fitPixmap = labelData.originalPix.scaled(
                labelData.label->size() - QSize(10, 10),
                Qt::KeepAspectRatio,
                Qt::SmoothTransformation
            );
            labelData.label->setPixmap(fitPixmap);
        }
    }
}

// 适配窗口调整缩略图尺寸
void ImageViewerWidget::adjustThumbnailSizeByWindow()
{
    QReadLocker uiLocker(&m_uiLock);
    if (m_imagesPerRow <= 0 || m_isRefreshing) return;

    // 精准计算可用宽度
    int spacing = m_imageLayout->spacing();
    int leftMargin = m_imageLayout->contentsMargins().left();
    int rightMargin = m_imageLayout->contentsMargins().right();
    int availableWidth = m_scrollArea->viewport()->width() - leftMargin - rightMargin - (m_imagesPerRow - 1) * spacing;
    int thumbnailWidth = availableWidth / m_imagesPerRow;

    // 限制尺寸范围（250~600px）
    thumbnailWidth = qBound(250, thumbnailWidth, 600);
    int thumbnailHeight = thumbnailWidth;

    // 尺寸变化时刷新图片
    if (thumbnailWidth != m_thumbnailWidth || thumbnailHeight != m_thumbnailHeight) {
        m_thumbnailWidth = thumbnailWidth;
        m_thumbnailHeight = thumbnailHeight;
        if (!m_imageFolder.isEmpty()) {
            uiLocker.unlock();
            refreshImages();
        }
    }
}

// 刷新图片列表
void ImageViewerWidget::refreshImages()
{
    QWriteLocker uiLocker(&m_uiLock);
    if (m_isRefreshing) return;
    m_isRefreshing = true;
    uiLocker.unlock();

    // 取消所有正在运行的任务
    cancelAllLoadTasks();

    // 清空旧数据
    QWriteLocker uiLocker2(&m_uiLock);
    m_pendingResults.clear();
    while (m_imageLayout->count() > 0) {
        QLayoutItem* item = m_imageLayout->takeAt(0);
        QLabel* label = qobject_cast<QLabel*>(item->widget());
        if (label) {
            label->removeEventFilter(this);
            label->deleteLater();
        }
        delete item;
    }
    m_imageLabelList.clear();
    uiLocker2.unlock();

    // 扫描图片文件夹
    QStringList imagePaths = loadPngImages();
    if (imagePaths.size() > m_maxImageCount) {
        imagePaths = imagePaths.mid(0, m_maxImageCount);
        qDebug() << "[ImageViewer] 加载前" << m_maxImageCount << "张图片";
    }

    // 创建图片标签
    QWriteLocker uiLocker3(&m_uiLock);
    for (int i = 0; i < imagePaths.size(); ++i) {
        ImageLabelData labelData;
        labelData.imgPath = imagePaths[i];
        labelData.isLoaded = false;
        labelData.isLoading = false;
        labelData.index = i;
        QLabel* thumbnailLabel = createThumbnailLabel(imagePaths[i], labelData, i);
        if (thumbnailLabel) {
            thumbnailLabel->installEventFilter(this);
            labelData.label = thumbnailLabel;
            m_imageLabelList.append(labelData);

            // 添加到网格布局
            int row = i / m_imagesPerRow;
            int col = i % m_imagesPerRow;
            m_imageLayout->addWidget(thumbnailLabel, row, col);
        }
    }
    uiLocker3.unlock();

    // 触发懒加载
    if (m_enableLazyLoad) {
        QTimer::singleShot(0, this, &ImageViewerWidget::checkVisibleImages);
    } else {
        QList<int> allIndices;
        for (int i = 0; i < m_imageLabelList.size(); ++i) {
            allIndices.append(i);
        }
        startLoadTasks(allIndices);
    }

    // 刷新完成
    QWriteLocker uiLocker4(&m_uiLock);
    m_isRefreshing = false;
    uiLocker4.unlock();
}

// 创建图片标签
QLabel* ImageViewerWidget::createThumbnailLabel(const QString &imgPath, ImageLabelData& data, int index)
{
    QLabel* label = new QLabel();
    label->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
    label->setMinimumSize(250, 250);
    label->setMaximumSize(600, 600);
    label->setAlignment(Qt::AlignCenter);
    label->setToolTip(QString("双击放大\n%1").arg(imgPath));
    label->setCursor(Qt::PointingHandCursor);
    // 抗锯齿样式，提升清晰度
    label->setStyleSheet("QLabel{background: #f8f8f8; border-radius: 4px; border: 1px solid #eee; padding: 5px; image-rendering: smooth;}");
    label->setText("加载中...");
    return label;
}

// 扫描文件夹中的PNG图片
QStringList ImageViewerWidget::loadPngImages()
{
    QStringList imagePaths;
    QReadLocker uiLocker(&m_uiLock);
    if (m_imageFolder.isEmpty()) {
        return imagePaths;
    }

    QDir dir(m_imageFolder);
    dir.setFilter(QDir::Files | QDir::NoDotAndDotDot);
    dir.setNameFilters(QStringList() << "*.png" << "*.PNG");
    dir.setSorting(QDir::Name);

    QFileInfoList fileList = dir.entryInfoList();
    for (const QFileInfo& fileInfo : fileList) {
        imagePaths.append(fileInfo.absoluteFilePath());
    }

    return imagePaths;
}

// 重置布局拉伸比例
void ImageViewerWidget::resetGridLayoutStretch()
{
    for (int i = 0; i < m_imageLayout->columnCount(); ++i) {
        m_imageLayout->setColumnStretch(i, 0);
    }
    for (int i = 0; i < m_imagesPerRow; ++i) {
        m_imageLayout->setColumnStretch(i, 1); // 均匀拉伸
    }
}

// 事件过滤器：监听双击事件
bool ImageViewerWidget::eventFilter(QObject *watched, QEvent *event)
{
    if (event->type() == QEvent::MouseButtonDblClick) {
        QMouseEvent* mouseEvent = static_cast<QMouseEvent*>(event);
        if (mouseEvent->button() == Qt::LeftButton) {
            QReadLocker uiLocker(&m_uiLock);

            // 找到被双击的图片标签
            for (const auto& labelData : m_imageLabelList) {
                if (watched == labelData.label && labelData.isLoaded) {
                    // 打开预览窗口
                    QTimer::singleShot(10, [originalPix = labelData.originalPix, parent = this]() {
                        ImagePreviewDialog* dialog = new ImagePreviewDialog(originalPix, parent);
                        dialog->show();
                    });
                    break;
                }
            }
            return true;
        }
    }

    return QWidget::eventFilter(watched, event);
}

// 取消所有加载任务
void ImageViewerWidget::cancelAllLoadTasks()
{
    QWriteLocker taskLocker(&m_taskLock);
    cancelAllLoadTasksUnlocked();
}

// 无锁版本：取消所有加载任务
void ImageViewerWidget::cancelAllLoadTasksUnlocked()
{
    m_threadPool->clear();

    // 释放信号量
    int used = m_maxConcurrentLoads - m_loadSemaphore.available();
    if (used > 0) {
        m_loadSemaphore.release(used);
    }

    // 删除任务
    qDeleteAll(m_runningTasks);
    m_runningTasks.clear();

    // 更新加载状态
    QWriteLocker uiLocker(&m_uiLock);
    for (auto& labelData : m_imageLabelList) {
        labelData.isLoading = false;
    }
}

// 设置图片文件夹
void ImageViewerWidget::setImageFolder(const QString &path)
{
    QWriteLocker uiLocker(&m_uiLock);
    m_imageFolder = path;

    QDir dir(path);
    if (!dir.exists()) {
        qWarning() << "[ImageViewer] 文件夹不存在：" << path;
        QMessageBox::warning(this, "警告", "图片文件夹不存在！");
        return;
    }

    if (!m_refreshTimer->isActive()) {
        m_refreshTimer->start();
    }

    uiLocker.unlock();
    QTimer::singleShot(100, this, &ImageViewerWidget::refreshImages);
    QTimer::singleShot(200, this, &ImageViewerWidget::adjustThumbnailSizeByWindow);
}

// 设置自动刷新间隔
void ImageViewerWidget::setRefreshInterval(int interval)
{
    if (interval >= 3000) { // 最小3秒，避免频繁刷新
        m_refreshInterval = interval;
        if (m_refreshTimer->isActive()) {
            m_refreshTimer->setInterval(interval);
        }
    } else {
        qWarning() << "[ImageViewer] 刷新间隔不能小于3000ms！";
    }
}

// 设置每行图片数
void ImageViewerWidget::setImagesPerRow(int count)
{
    QWriteLocker uiLocker(&m_uiLock);
    if (count <= 0 || count == m_imagesPerRow || m_isRefreshing) {
        return;
    }
    m_imagesPerRow = count;
    resetGridLayoutStretch();
    uiLocker.unlock();
    adjustThumbnailSizeByWindow();
}

// 设置最大加载图片数
void ImageViewerWidget::setMaxImageCount(int count)
{
    if (count <= 0 || count > 200) { // 限制最大200张，避免内存溢出
        qWarning() << "[ImageViewer] 最大图片数需在1-200之间！";
        return;
    }
    QWriteLocker uiLocker(&m_uiLock);
    m_maxImageCount = count;
}

// 设置最大并发加载数
void ImageViewerWidget::setMaxConcurrentLoads(int count)
{
    if (count <= 0 || count > 16) { // 限制最大16个并发，避免CPU过载
        qWarning() << "[ImageViewer] 并发数需在1-16之间！";
        return;
    }
    QWriteLocker taskLocker(&m_taskLock);
    int oldCount = m_maxConcurrentLoads;
    m_maxConcurrentLoads = count;
    int diff = m_maxConcurrentLoads - oldCount;
    if (diff > 0) {
        m_loadSemaphore.release(diff);
    } else if (diff < 0) {
        int available = m_loadSemaphore.available();
        int needAcquire = qMin(-diff, available);
        if (needAcquire > 0) {
            m_loadSemaphore.acquire(needAcquire);
        }
    }
    m_threadPool->setMaxThreadCount(m_maxConcurrentLoads);
}

// 启用/禁用懒加载
void ImageViewerWidget::setLazyLoad(bool enable)
{
    m_enableLazyLoad = enable;
    if (enable && !m_imageLabelList.isEmpty()) {
        checkVisibleImages();
    }
}

四、使用示例

在其他窗口中调用 ImageViewerWidget：

#include "ImageViewerWidget.h"
#include <QPushButton>
#include <QVBoxLayout>

class AnalysisResultWidget : public QWidget {
    Q_OBJECT
public:
    AnalysisResultWidget(QWidget* parent = nullptr) : QWidget(parent) {
        // 创建按钮
        QPushButton* openBtn = new QPushButton("打开图片文件夹", this);
        connect(openBtn, &QPushButton::clicked, this, &AnalysisResultWidget::on_openBtn_clicked);

        // 创建图片浏览器
        m_imageViewer = new ImageViewerWidget(this);

        // 布局
        QVBoxLayout* layout = new QVBoxLayout(this);
        layout->addWidget(openBtn);
        layout->addWidget(m_imageViewer);
    }

private slots:
    void on_openBtn_clicked() {
        QString folder = QFileDialog::getExistingDirectory(this, "选择图片文件夹");
        if (!folder.isEmpty()) {
            m_imageViewer->setImageFolder(folder);
            m_imageViewer->setRefreshInterval(10000); // 10秒自动刷新
            m_imageViewer->setImagesPerRow(2); // 每行2张图片
        }
    }

private:
    ImageViewerWidget* m_imageViewer;
};

五、开发经验总结

（一）编译 / 链接错误排查技巧

变量 / 函数名不一致：严格保持头文件声明与源文件实现的名称一致（包括大小写、后缀，如 originalPix 而非 original）；
Qt 版本兼容性：使用旧版本 Qt（如 5.14）时，避免使用高版本新增接口（如 QWriteLocker::relockForWrite），需使用兼容方案；
链接错误 LNK2019/LNK2001：
- 检查头文件声明的所有函数是否都有实现；
- 确认函数签名完全一致（返回值、参数类型、const 修饰、虚函数标记）；
- 检查源文件是否已添加到项目编译列表（.pro 文件的 SOURCES 中）；
Qt 元对象系统错误：包含槽函数的类必须添加 Q_OBJECT 宏，自定义结构体需用 Q_DECLARE_METATYPE 注册。