Qt4到Qt5迁移实战：启用废弃API解决QHeaderView兼容性问题

在 Qt框架 的发展历程中，Qt5 作为一个重要的里程碑版本，在性能、架构和模块化方面带来了显著改进，但同时也对部分 Qt4 中的 API 进行了废弃（deprecated）或移除（removed）处理。这给许多从 Qt4 升级到 Qt5 的项目带来了兼容性挑战。

本文将详细探讨以下内容：

• Qt5 中废弃机制的工作原理；
• 如何通过 QT_DISABLE_DEPRECATED_BEFORE 宏重新启用 Qt4 风格的旧 API；
• 以 QHeaderView::setMovable() 为例，展示具体使用方法；
• 提供完整的代码示例与最佳实践建议；
• 分析启用旧 API 的利弊及迁移策略。

一、背景：Qt5 中的 API 废弃机制

Qt 项目组为了保持框架的现代化和可维护性，在新版本中会逐步淘汰过时的函数、类或行为。这些被标记为deprecated的 API 默认不会被编译进程序（除非显式启用），以鼓励开发者使用更现代、更安全的替代方案。

例如，在 Qt4 中，QHeaderView提供了如下方法：

void setMovable(bool movable); // Qt4 风格
bool isMovable() const;

但在 Qt5 中，这些方法被重命名为：

void setSectionsMovable(bool movable); // Qt5 新命名
bool sectionsMovable() const;

同时，Qt5 保留了setMovable()作为兼容性别名，但默认不编译，除非你明确告诉编译器“允许使用旧版 API”。

二、启用 Qt4 废弃 API 的关键：QT_DISABLE_DEPRECATED_BEFORE

Qt 使用一个宏QT_DISABLE_DEPRECATED_BEFORE来控制哪些版本之前的废弃 API 被禁用。

宏的含义

• QT_DISABLE_DEPRECATED_BEFORE=0x050000 表示：禁用 Qt 5.0 之前的所有废弃 API（即只允许 Qt5+ 的 API）。
• QT_DISABLE_DEPRECATED_BEFORE=0 表示：不禁用任何废弃 API，即使它们来自 Qt3 或 Qt4。

✅ 因此，若你想在 Qt5 中继续使用 Qt4 的setMovable()，只需在项目配置文件中添加：

DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0

版本编码规则

Qt 使用十六进制编码表示版本号：

版本	十六进制值
Qt 4.0	0x040000
Qt 4.8	0x040800
Qt 5.0	0x050000
Qt 5.15	0x050F00
Qt 6.0	0x060000

默认情况下，Qt5 的qconfig.h中定义了：

#define QT_DISABLE_DEPRECATED_BEFORE 0x050000

这意味着所有在 Qt5.0 之前被标记为QT_DEPRECATED的函数都会被#ifdef屏蔽。

三、实战示例：在 Qt5 中使用 QHeaderView::setMovable()

步骤 1：创建 Qt Widgets 项目

假设你有一个基于 Qt5 的 GUI 项目，包含一个QTableWidget。

步骤 2：在 .pro 文件中启用旧 API

编辑你的项目文件（如myapp.pro）：

QT       += core widgets
CONFIG   += c++11
TARGET   = MyTableApp
TEMPLATE = app
# 启用所有废弃 API（包括 Qt4 的）
DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0
SOURCES += main.cpp \
           mainwindow.cpp
HEADERS += mainwindow.h
FORMS   += mainwindow.ui

🔔 注意：DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0是关键！

步骤 3：在代码中使用 Qt4 风格的 API

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <QTableWidget>

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

mainwindow.cpp

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

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

    // 使用 Qt4 风格的 setMovable（在 Qt5 中默认不可用）
    ui->tableWidget->horizontalHeader()->setMovable(false); // ← 关键调用！

    // 添加测试数据
    ui->tableWidget->setColumnCount(3);
    ui->tableWidget->setHorizontalHeaderLabels({"姓名", "年龄", "城市"});
    ui->tableWidget->setRowCount(2);
    ui->tableWidget->setItem(0, 0, new QTableWidgetItem("张三"));
    ui->tableWidget->setItem(0, 1, new QTableWidgetItem("25"));
    ui->tableWidget->setItem(0, 2, new QTableWidgetItem("北京"));
}

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

步骤 4：编译运行

• 如果没有添加 DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0，编译会报错：error: 'class QHeaderView' has no member named 'setMovable'
• 添加后，编译成功，且列拖动被禁用。

四、对比：Qt4 vs Qt5 的正确做法

功能	Qt4 写法	Qt5 推荐写法
禁止列拖动	header->setMovable(false);	header->setSectionsMovable(false);
获取是否可移动	header->isMovable();	header->sectionsMovable();

虽然启用旧 API 可以快速迁移，但长期来看应逐步替换为新 API。

五、启用旧 API 的利与弊

✅ 优点

• 快速迁移：无需大规模修改遗留代码；
• 降低风险：避免因 API 替换引入新 bug；
• 兼容第三方库：某些老库依赖 Qt4 风格 API。

❌ 缺点

• 技术债积累：代码停留在过时接口上；
• 未来升级困难：Qt6 已彻底移除大量 Qt4/5 废弃 API；
• 可能掩盖问题：旧 API 可能存在性能或安全缺陷。

📌 建议：仅在过渡期使用QT_DISABLE_DEPRECATED_BEFORE=0，并制定迁移计划。

六、更精细的控制：按需启用特定版本的 API

如果你只想启用 Qt4.8 的 API，但禁用更早的（如 Qt3），可以写：

DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0x040800

这样既能使用setMovable()（在 Qt4.2 引入），又不会启用过于古老的接口。

七、Qt6 的注意事项

Qt6彻底移除了大量在 Qt5 中仅标记为 deprecated 的 API。例如：

• QHeaderView::setMovable() 在 Qt6 中完全不存在；
• 即使设置 QT_DISABLE_DEPRECATED_BEFORE=0 也无法使用。

因此，强烈建议：在 Qt5 阶段就完成向新 API 的迁移，不要依赖旧接口长期存在。

八、总结

问题	解决方案
Qt5 中无法使用setMovable()？	在.pro文件中添加DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0
想兼容 Qt4 代码？	启用旧 API 作为临时手段
长期维护？	改用setSectionsMovable()等 Qt5+ 标准 API

通过合理使用QT_DISABLE_DEPRECATED_BEFORE，你可以在 Qt5 中平滑过渡 Qt4 项目。但请记住：这只是桥梁，不是终点。真正的目标是拥抱现代 Qt API，构建更健壮、可维护的应用程序。