利用上下文属性将 C++ 对象嵌入 QML 界面

准备条件

在开始之前，请确保您的项目已正确配置 Qt 开发环境，并包含必要的头文件。主要的交互入口位于 C++ 的 main.cpp 主程序中，通过创建视图窗口后的根上下文（Root Context）进行数据注入。

一、设置简单的上下文属性

QQmlContext 允许直接将值暴露给 QML 作用域。最简单的方式是传递基础类型值，例如日期时间字符串。

第1步：定义 QML 绑定需求

假设有一个文本组件需要显示当前系统时间，但 QML 内部未定义该变量：

// MyItem.qml
import QtQuick 2.0
Text 
{ 
    text: currentDateTime
}

第2步：在 C++ 中注入数据

在加载 QML 源之前，使用 rootContext->setContextProperty() 方法将 C++ 数据映射为 QML 名称：

QQuickView view;
view.rootContext()->setContextProperty("currentDateTime", QDateTime::currentDateTime());
view.setSource(QUrl::fromLocalFile("MyItem.qml"));
view.show();

由于 QML 中的表达式绑定是在特定上下文中计算的，修改上下文会导致重新计算相关绑定。因此，通常建议在应用程序初始化阶段设定此类静态属性，避免频繁修改导致性能波动。

二、将自定义 C++ 对象设为上下文属性

除了原始数据类型，更多场景下需要将自定义的 QObject 子类实例传递给 QML。这使得 QML 不仅能读取数据，还能调用 C++ 函数并监听信号。

第1步：声明 C++ 数据类

继承自 QObject 并通过 Q_INVOKABLE 或信号/槽机制公开功能：

class ApplicationData : public QObject
{
    Q_OBJECT
public:
    Q_INVOKABLE QDateTime getCurrentDateTime() const 
    {
        return QDateTime::currentDateTime();
    }
};

第2步：注册实例并处理连接

在 main 函数中将其实例化并传入上下文，随后在 QML 中通过 Connections 组件监听其状态变化：

// C++ 端
ApplicationData data;
view.rootContext()->setContextProperty("applicationData", &data);

// QML 端
import QtQuick 2.0
Text 
{ 
    text: applicationData.getCurrentDateTime()
    Connections 
    {
        target: applicationData
        onDataChanged: console.log("The application data changed!")
    }
}

注意：若需将返回的日期时间在 QML 中格式化，可使用 Qt.formatDateTime() 等内置函数辅助转换。

三、C++ 数据模型嵌入示例

对于动态列表或表格数据，直接传递单个对象并不适用，通常需要引入模型结构。以下演示三种常见的模型传递方式。

第1步：传入 QStringList 模型

适用于简单的字符串列表展示。利用 QVariant::fromValue 进行装箱转换：

QStringList dataList;

对应的 QML 列表视图如下：

ListView 
{
    model: myModel
    delegate: Rectangle 
    {
        height: 25; width: 100
        Text { text: modelData } // 直接使用 modelData 获取字符串
    }
}

第2步：传入 QObject 列表模型

当列表中每条记录都包含多个属性（如名称、颜色）时，可传递 QList<QObject*>：

QList<QObject*> dataList;
dataList.append(new DataObject("Item 1", "red"));
// ... 添加其他项
QQmlContext *ctxt = view.rootContext();
ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));

在 QML 中可以通过 model.modelData 访问具体的子对象属性：

delegate: Rectangle 
{
    color: model.modelData.color
    Text { text: name } // 自动识别为 DataObject 的属性
}

第3步：自定义 QAbstractItemModel

对于复杂的业务数据，建议实现标准的 QAbstractListModel，以便更好地控制行号更新和数据角色分发：

// 定义角色枚举
enum AnimalRoles {
    TypeRole = Qt::UserRole + 1,
    SizeRole
};

QHash<int, QByteArray> roleNames() const {
    QHash<int, QByteArray> roles;
    roles[TypeRole] = "type";
    roles[SizeRole] = "size";
    return roles;
}

// 在主函数中实例化并设置
AnimalModel model;
model.addAnimal(Animal("Wolf", "Medium"));
ctxt->setContextProperty("myModel", &model);

在 QML 中引用自定义的角色名称即可：

delegate: Text { text: "Animal: " + type + ", " + size }