1. 为什么你需要QtPropertyBrowser在Qt的世界里做界面开发尤其是涉及到复杂参数配置、设备属性管理或者游戏编辑器这类工具时你肯定遇到过这样的烦恼界面上需要展示和编辑一大堆不同类型的属性——整数、浮点数、字符串、颜色、枚举下拉框甚至文件路径。如果每个属性都手动去拖Label、LineEdit、ComboBox然后写一堆信号槽来同步数据那工作量简直让人头皮发麻代码也会变得又臭又长后期维护更是噩梦。这时候你就需要一个像QtPropertyBrowser这样的神器。它本质上是一个属性浏览器控件你可以把它想象成一个高度智能、可定制的“属性表格”。你只需要定义好属性的类型、名称和值它就能自动生成对应的编辑界面比如数字用SpinBox颜色用ColorDialog按钮枚举用ComboBox并且自动处理数据的显示、编辑和验证。我们平时在Qt Designer里看到的那个可以折叠分组的属性窗口其核心思想就和它类似。使用QtPropertyBrowser你能把原本需要几百行代码才能搞定的属性编辑面板用几十行代码优雅地实现极大地提升了开发效率和界面的专业度。然而这个强大的工具在Qt 5及以后的版本中并没有被直接包含在官方的二进制安装包里。官方源码里虽然有它但默认不编译。网上能找到的很多资料和源码还是Qt 4时代的直接用在Qt 5上会报各种编译错误。这就是为什么我们需要一个从源码编译到设计器集成的完整指南。今天我就以最常用的Windows平台、VS2019配合Qt 5.12.2这个环境为例手把手带你走通整个流程把那些令人头疼的编译错误一个个解决掉最后让它乖乖地在你的Qt Designer里出现实现可视化拖拽设计。2. 前期准备获取源码与搭建环境工欲善其事必先利其器。在开始编译之前我们需要把“原材料”和“厨房”都准备好。第一步获取QtPropertyBrowser的源码。这里主要有两个来源对应着两种不同的配置方式也决定了后续步骤的差异。第一种方式是使用独立的QtPropertyBrowser项目源码。这个项目最初源于Qt Solutions后来独立出来。你可以在GitHub上搜索“qtpropertybrowser”找到它或者从一些历史存档网站下载。下载后得到一个压缩包解压后会看到qtpropertybrowser文件夹里面包含了所有源代码和示例。这是我们今天主要讲解的方式因为它更通用不依赖于你是否安装了Qt的完整源码。第二步确认你的开发环境。我假设你已经按照常规流程安装好了Visual Studio 2019和Qt 5.12.2MSVC 2017 64-bit版本并且安装了用于VS的Qt Visual Studio Tools插件以前叫Qt VS Tools。这个插件能让你在VS里直接打开和管理.pro项目文件非常方便。打开VS2019你应该能在菜单栏看到“Qt VS Tools”选项。同时请确保你的系统环境变量Path中已经添加了Qt的bin目录例如C:\Qt\5.12.2\msvc2017_64\bin和对应的编译器路径这对于后续的qmake和编译步骤至关重要。第三种准备方式是使用Qt自带的源码。如果你在安装Qt时勾选了“Source”组件那么你可以在Qt的安装目录下找到它路径通常是Qt\5.12.2\Src\qttools\src\shared\qtpropertybrowser。这种方式的好处是源码版本与你的Qt版本完全匹配但缺点是你必须安装了源码且集成到设计器的步骤略有不同。我们会在文章后面简要介绍这种方法作为备选方案。3. 编译独立源码从Qt4到Qt5的迁移攻坚战拿到独立源码后你会发现它通常是为Qt 4编写的。在Qt 5中模块结构发生了巨大变化最著名的就是QtGui被拆分因此直接编译必然会报错。别怕跟着我一步步修改这些错误都有固定的解决模式。### 3.1 打开项目与首次编译尝试解压源码进入qtpropertybrowser目录你会发现里面有几个子目录和.pro文件。我们需要编译的是buildlib目录下的工程这个工程专门用于生成库文件。用VS2019的“Qt VS Tools” - “Open Qt Project File (.pro)...”打开buildlib\buildlib.pro文件。打开后VS会加载这个项目。首先我们需要确认项目的编译配置。在VS的解决方案资源管理器中右键buildlib项目选择“属性”。在“Qt Project Settings”里确保“Qt Installation”指向了你安装的Qt 5.12.2 (MSVC2017 64-bit)。然后在“Configuration Properties” - “General”中查看“Configuration Type”。默认可能是“Dynamic Library (.dll)”我们先保持默认尝试生成一下。右键项目点击“生成”。果不其然编译会立刻失败输出窗口会抛出一连串错误。这正是我们预料之中的因为这些错误正是Qt4到Qt5的“代沟”。我们接下来就化身“代码医生”逐个诊断并修复它们。### 3.2 逐个击破经典编译错误这些错误虽然看起来多但归纳起来就那么几类修复起来有章可循。错误一头文件找不到QtGui/QWidget等。这是最常见的问题。在Qt 5中QWidget、QDialog等GUI组件被移到了新的QtWidgets模块中。错误信息示例fatal error C1083: Cannot open include file: QtGui/QWidget: No such file or directory解决方案在报错的源文件通常是.cpp或.h文件中找到类似#include QtGui/QWidget的语句将其修改为#include QtWidgets/QWidget。通常需要修改的文件包括qteditorfactory.cpp、qtpropertymanager.cpp等。你可以使用VS的“在文件中查找”功能批量查找#include QtGui/并替换。错误二QApplication::UnicodeUTF8已被移除。在Qt 4中QApplication::UnicodeUTF8常用于tr函数但在Qt 5中这个枚举值被移除了因为默认就是UTF-8。错误信息示例涉及tr函数调用参数错误。解决方案找到所有类似tr(Some Text, 0, QApplication::UnicodeUTF8)的代码直接移除第二个和第三个参数改为tr(Some Text)。特别注意移除的是“, 0, QApplication::UnicodeUTF8”这一整部分包括前面那个逗号。例如在qtpropertybrowser.cpp中就有多处需要修改。错误三qVariantValue和qVariantSetValue等函数过时。Qt 5推荐使用更安全的模板函数来替代旧的qVariantValue等。解决方案将qVariantValueT(variant)替换为variant.valueT()或qvariant_castT(variant)。将qVariantSetValue(variant, value)替换为variant.setValue(value)。 在qtpropertymanager.cpp等文件中搜索这些函数并进行替换。错误四qFindChildren全局函数被移除。Qt 5将一些全局工具函数移到了对应的类中作为成员函数。解决方案将qFindChildrenType *(object)替换为object-findChildrenType *()。例如在qtpropertymanager.cpp中查找并修改。错误五setMovable和setResizeModeQHeaderView相关。这些是QHeaderView类的方法名在Qt 5中发生了变化。解决方案将setMovable()替换为setSectionsMovable()。将setResizeMode()替换为setSectionResizeMode()。 这些错误通常出现在qttreepropertybrowser.cpp文件中。错误六Q_TYPENAME宏错误。这个宏在Qt 5中不再需要。解决方案简单地将代码中的Q_TYPENAME替换为标准的typename关键字即可。错误七链接错误无法解析的外部符号。当你解决了大部分编译错误后可能会遇到链接错误提示找不到QWidget等类的相关符号。这是因为项目文件.pro没有正确链接widgets模块。解决方案打开buildlib.pro文件在QT变量的声明中确保包含了widgets。通常原始的QT行可能只有core gui你需要将其修改为QT core gui widgets保存后在VS里右键项目选择“Run qmake”然后重新生成项目。经过以上七步“手术”再次点击“生成”恭喜你项目应该可以成功编译了。在输出目录通常是debug或release子目录下你会找到生成的qtpropertybrowser.dll动态链接库文件。4. 生成静态库与设计器插件文件只有.dll文件有时候还不够方便特别是当你希望将属性浏览器功能静态链接到你的程序中或者需要将其集成到Qt Designer时我们还需要.lib静态库或导入库和设计器插件文件。### 4.1 如何生成.lib文件如果你在输出目录只看到了.dll而没有.lib不要慌。这是因为项目配置默认只生成动态库的.dll。要生成.lib文件我们需要修改项目配置类型。在VS中右键buildlib项目选择“属性”。在“Configuration Properties” - “General”中找到“Configuration Type”。将其从“Dynamic Library (.dll)”修改为“Static Library (.lib)”。然后非常重要的一步你还需要修改项目属性中的“Qt Project Settings”。因为改为静态库后Qt的构建系统需要知道。一个更简单通用的方法是直接修改buildlib.pro文件。打开buildlib.pro在文件末尾添加一行CONFIG staticlib这行代码告诉qmake我们要构建静态库。保存文件在VS中右键项目先选择“Run qmake”来应用.pro文件的更改然后重新“生成”。这次在输出目录下你应该能同时看到qtpropertybrowser.lib静态库和qtpropertybrowser.dll如果需要的话动态库可能也会生成取决于配置。实际上对于我们的目的生成静态库.lib就足够了因为集成到设计器通常使用静态链接的方式。### 4.2 编译设计器插件关键步骤要让QtPropertyBrowser的控件出现在Qt Designer的 widget box 里我们需要编译一个设计器插件。幸运的是源码包里已经提供了这个插件工程。在源码目录下找到designer文件夹里面有一个designer.pro文件。同样用VS的Qt插件打开这个项目。打开后你可能还需要根据Qt5环境进行一些微调但通常这个插件工程比核心库要简单可能不需要修改就能直接编译。在编译之前检查一下designer.pro文件。它里面应该有一行类似TARGET $$qtLibraryTarget(qtpropertybrowser)这定义了插件的输出名称。确保QT变量包含了designer和widgets模块例如QT core gui widgets designer。直接尝试生成这个项目。如果成功你会在designer目录的debug或release子文件夹下找到一个名为qtpropertybrowser.dll或类似名称的插件文件。注意这个qtpropertybrowser.dll是设计器插件和之前buildlib生成的库文件不是同一个东西虽然名字可能相同。为了区分我建议你在designer.pro里修改一下TARGET比如改为qtpropertybrowserplugin。5. 集成到Qt Designer与项目中使用库和插件都编译好了现在就是享受成果的时刻把它们用起来。### 5.1 安装设计器插件要让Qt Designer识别我们的插件需要将编译好的设计器插件DLL文件放到Qt Designer的插件目录下。这个路径通常是C:\Qt\5.12.2\msvc2017_64\plugins\designer将designer项目生成的qtpropertybrowserplugin.dll或者你命名的其他名字复制到这个目录下。如果目录不存在可以手动创建designer文件夹。### 5.2 在Qt Designer中验证关闭所有已打开的Qt Designer或Qt Creator。重新打开Qt Creator并进入设计模式或者单独打开Qt安装目录\bin下的designer.exe。在左侧的Widget Box里滚动查找你应该能看到多出了一个名为“Property Browser”的分组里面包含了QtTreePropertyBrowser、QtGroupBoxPropertyBrowser和QtButtonPropertyBrowser这三个控件。现在你可以像使用普通的QPushButton、QLineEdit一样将它们直接拖拽到你的窗体上了### 5.3 在项目中使用提升法与直接代码创建在设计器里拖拽使用是最直观的。但有时我们可能需要在代码中动态创建或者在已有的QWidget上“提升”为属性浏览器控件。方法一提升法Promotion这是在设计器里使用自定义控件的标准方法。当你拖一个普通的QWidget到窗体上右键它选择“提升为...”。在“提升的类名称”里填入QtTreePropertyBrowser在“头文件”里填入qtpropertybrowser.h或QtTreePropertyBrowser的实际头文件路径如果头文件不在标准包含路径可能需要填写相对或绝对路径。点击“添加”再点击“提升”这个QWidget就变成了一个属性浏览器控件。这种方法要求你的项目在编译时能正确链接到我们之前编译的qtpropertybrowser.lib库并包含头文件。方法二直接代码集成在你的Qt应用程序项目中需要做以下几步添加头文件路径在项目属性或.pro文件的“附加包含目录”中添加QtPropertyBrowser源码的src目录路径。添加库依赖如果使用静态库.lib在项目属性的“链接器”-“输入”-“附加依赖项”中添加qtpropertybrowser.lib的完整路径或通过库目录引用。同时在“C/C”-“代码生成”中将“运行时库”设置为“多线程(/MT)”或“多线程调试(/MTd)”以匹配静态库的配置。如果使用动态库.dll除了链接.lib导入库还需要确保程序运行时能找到qtpropertybrowser.dll可以放在exe同级目录或系统PATH中。在代码中创建包含头文件#include QtTreePropertyBrowser然后就可以像使用普通Qt控件一样new QtTreePropertyBrowser了。接着你需要创建对应的QtIntPropertyManager整数属性管理器、QtLineEditFactory字符串编辑器工厂等将属性、管理器和编辑器工厂关联起来最后将属性添加到浏览器中。网上有丰富的示例代码展示了这一流程。6. 备选方案使用Qt自带源码进行集成如果你在安装Qt时选择了源码那么还有一条更“官方”一点的路径。你可以在Qt\5.12.2\Src\qttools\src\shared\qtpropertybrowser找到源码。要使用它你不需要单独编译库而是可以直接在你的项目文件中引入对应的.pri文件。在你的应用程序的.pro文件中添加一行include($$[QT_INSTALL_PREFIX]/../Src/qttools/src/shared/qtpropertybrowser/qtpropertybrowser.pri)这行代码会将QtPropertyBrowser的源码直接编译进你的项目。然后你就可以直接在代码中包含头文件如#include QtTreePropertyBrowser并使用相关类了。这种方法的好处是版本绝对匹配无需处理额外的库文件。但缺点也很明显它要求所有开发成员的Qt安装路径下都有源码并且你的项目构建会变慢因为每次都要编译这部分代码。另外这种方法通常不会自动生成设计器插件你仍然需要单独编译我们前面提到的designer插件工程或者手动提升控件来使用。我个人的经验是对于团队协作和项目部署优先推荐使用第一种方法编译独立的静态库。这样库只需要编译一次所有项目都可以链接使用设计器插件也能统一安装环境配置最干净。而使用Qt自带源码的方式更适合快速尝鲜或者个人小项目。无论选择哪种打通从源码到设计器这条路的成就感以及后续开发中因这个强大工具而提升的效率都会让你觉得今天的折腾是完全值得的。