如何在QML ComboBox中正确使用C++结构体数组作为模型

直接将QList<testStruct>类型的属性暴露给QML作为ComboBox模型时，QML引擎默认不会自动把Q_GADGET标记的结构体属性解析为视图可识别的命名角色，ComboBox设置的textRole、valueRole匹配不到对应字段，就会出现下拉项显示异常、currentText/currentValue取值为空的问题。

两种方案按需选择即可，其中方案1改动量最小。

方案1：用QVariantList包装结构体列表 #

不需要新增自定义类，仅修改现有AppEngine的代码即可：

1. 调整AppEngine的属性、成员变量、接口返回值类型，将原来的QList<testStruct>替换为QVariantList，对应AppEngine.h修改如下：

// 原Q_PROPERTY修改为
Q_PROPERTY(QVariantList testStructs READ testStructs NOTIFY testStructsChanged);

public:
  explicit AppEngine(QObject *parent = nullptr);
  // 原接口返回值修改为QVariantList
  QVariantList testStructs();

private:
  // 原成员变量修改为QVariantList类型
  QVariantList m_testStructs;

头文件中已写的Q_DECLARE_METATYPE(testStruct)保留即可，不需要删除。

2. 修改AppEngine.cpp中的列表填充、返回逻辑，将每个结构体实例包装为QVariant再存入列表：

AppEngine::AppEngine(QObject *parent)
  : QObject{parent}
{
  testStruct newStruct1, newStruct2;
  newStruct1.m_text = "text1";
  newStruct1.m_value = "value1";
  newStruct2.m_text = "text2";
  newStruct2.m_value = "value2";
  // 结构体转QVariant存入列表
  m_testStructs << QVariant::fromValue(newStruct1) << QVariant::fromValue(newStruct2);
  qDebug() << "m_testStructs.length():" << m_testStructs.length();
}

QVariantList AppEngine::testStructs()
{
  qDebug() << "testStructs()";
  return m_testStructs;
}

修改完成后QML层代码不需要做任何调整，重新编译运行即可正常识别角色。

方案2：自定义QAbstractListModel实现（适配动态列表场景） #

如果后续需要对列表做动态增删改、自动触发UI刷新，建议自定义列表模型类，显式声明角色映射：

1. 新增继承自QAbstractListModel的模型类，重写必要接口：

#include <QAbstractListModel>
#include <QList>
#include "appengine.h"

class TestStructListModel : public QAbstractListModel
{
  Q_OBJECT
public:
  enum ModelRoles {
    TextRole = Qt::UserRole + 1,
    ValueRole
  };

  int rowCount(const QModelIndex &parent = QModelIndex()) const override
  {
    return m_list.size();
  }

  QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override
  {
    if (!index.isValid() || index.row() >= m_list.size())
      return QVariant();
    const testStruct &item = m_list.at(index.row());
    switch (role) {
      case TextRole: return item.m_text;
      case ValueRole: return item.m_value;
      default: return QVariant();
    }
  }

  QHash<int, QByteArray> roleNames() const override
  {
    return {
      {TextRole, "text"},
      {ValueRole, "value"}
    };
  }

  // 示例：新增条目接口，调用后UI自动刷新
  void append(const testStruct &item)
  {
    beginInsertRows(QModelIndex(), m_list.size(), m_list.size());
    m_list.append(item);
    endInsertRows();
  }

private:
  QList<testStruct> m_list;
};

2. 在AppEngine中暴露该模型的实例给QML，将其设置为ComboBox的model即可，ComboBox原有textRole、valueRole配置不需要修改。

修复完成后运行程序，ComboBox下拉项会正常显示text1、text2，点击选项时控制台输出正确的取值结果：

qml: currentIndex: 0 ; currentText: text1 ;currentValue: value1
qml: currentIndex: 1 ; currentText: text2 ;currentValue: value2

内容的提问来源于stack exchange，提问作者Prain