将含QAbstractListModel属性的QObject设为QMLEngine根上下文属性后ListView为空问题

我之前也碰到过一模一样的坑，这种情况往往是几个容易忽略的细节没处理到位，咱们一步步来排查：

1. 先检查Q_PROPERTY的声明是否规范 #

QML对属性的响应依赖于NOTIFY信号，这是很多人容易漏掉的点：

// 正确的声明示例（只读属性也要保留NOTIFY）
Q_PROPERTY(QAbstractListModel* myModel READ myModel NOTIFY myModelChanged)

• 如果你的模型是动态赋值的，一定要在赋值后emit myModelChanged()信号，否则QML根本感知不到模型的变化。
• 确保READ函数返回的是正确的模型实例，别返回空指针或者临时对象。

2. 确认模型类的核心实现没出错 #

QAbstractListModel的核心是三个函数，少一个都不行：

（1）必须重写rowCount() #

这个函数告诉QML模型有多少行数据：

int MyListModel::rowCount(const QModelIndex& parent) const {
    // m_items是你存储数据的容器，比如QList<MyItem>
    return m_items.size();
}

（2）必须重写data() #

要根据角色返回对应的数据，还要做索引有效性检查：

QVariant MyListModel::data(const QModelIndex& index, int role) const {
    if (!index.isValid() || index.row() >= m_items.size())
        return QVariant();
    
    const MyItem& item = m_items[index.row()];
    switch(role) {
        case NameRole: return item.name;
        case AgeRole: return item.age;
        default: return QVariant();
    }
}

（3）必须重写roleNames() #

把C++里的角色常量映射成QML能识别的字符串，这是最容易踩坑的地方：

// 先在类里定义角色常量
enum Roles {
    NameRole = Qt::UserRole + 1,
    AgeRole
};

// 重写roleNames
QHash<int, QByteArray> MyListModel::roleNames() const {
    QHash<int, QByteArray> roles;
    roles[NameRole] = "name"; // 这个字符串要和QML delegate里用的属性名一致
    roles[AgeRole] = "age";
    return roles;
}

3. 检查根上下文属性的设置时机和生命周期 #

• 一定要在engine.load()之前设置根上下文属性，而且你的QObject实例不能是临时对象：

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;

    // 给实例设置父对象（比如app），避免被提前销毁
    MyDataObject* dataObj = new MyDataObject(&app);
    engine.rootContext()->setContextProperty("myData", dataObj);

    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

4. QML端的绑定要对应 #

先验证模型是否被正确识别，再看delegate的写法：

// 先加个Text看模型行数，确认模型是否绑定成功
Text { text: "模型行数：" + myData.myModel.count }

ListView {
    width: 300; height: 400
    model: myData.myModel // 要和Q_PROPERTY的名字完全对应
    delegate: Text { 
        text: name // 要和roleNames里的字符串完全对应
        font.pixelSize: 16
    }
}

5. 调试小技巧 #

• 在rowCount()和data()里加qDebug()输出，看看QML有没有调用这两个函数：如果没调用，说明模型没绑定上；如果调用了但返回空，就是数据的问题。
• 用Qt Creator的QML Debugger查看根上下文，直接检查myData.myModel的属性和数据，一目了然。

一般来说，按照这个流程排查，基本都能找到问题——我当初就是漏写了roleNames()，折腾了半天😂

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