如何从C++更新QML中的QImage并获取ImageItem引用？

问题背景 #

我目前正在实现从C向QML更新QImage的功能，参考实现了QQuickPaintedItem（自定义为ImageItem），初始图片能正常显示，但当C端收到FileWatcher的文件变化信号时，找不到正确的方式更新QImage。相关代码如下：

QML代码

ImageItem { 
    id: liveImageItem 
    height: parent.height 
    width: parent.width 
    objectName: "liveImageItem" 
}

注册代码

qmlRegisterType<QUIQImageItem>("imageItem", 1, 0, "ImageItem");

ImageItem的C++实现

ImageItem::ImageItem(QQuickItem *parent) : QQuickPaintedItem(parent) {
    qDebug() << Q_FUNC_INFO << "initializing new item, parent is: " << parent;
    this->current_image = QImage(":/resources/images/logo.png");
}

void ImageItem::paint(QPainter *painter) {
    qDebug() << Q_FUNC_INFO << "paint requested...";
    QRectF bounding_rect = boundingRect();
    QImage scaled = this->current_image.scaledToHeight(bounding_rect.height());
    QPointF center = bounding_rect.center() - scaled.rect().center();
    if (center.x() < 0) center.setX(0);
    if (center.y() < 0) center.setY(0);
    painter->drawImage(center, scaled);
}

QImage ImageItem::image() const {
    qDebug() << Q_FUNC_INFO << "image requested...";
    return this->current_image;
}

void ImageItem::setImage(const QImage &image) {
    qDebug() << Q_FUNC_INFO << "setting new image...";
    this->current_image = image;
    emit imageChanged();
    update();
}

我尝试用以下两种方式获取ImageItem引用，但返回列表始终为空：

QList<ImageItem*> res = engine->findChildren<ImageItem*>();

QList<ImageItem*> res = engine->findChildren<ImageItem*>("liveImageItem");

想请教：如何正确在C++端拿到这个Item的引用并调用setImage？这种方式可行吗？还是有其他更好的方案？

解决方案 #

一、先解决findChildren返回空的问题

你的查找失败大概率是以下几个原因，逐一排查：

1. 时机过早：调用findChildren时QML组件还没加载完成。要确保在QML初始化完成后再查找，比如监听QQmlApplicationEngine::objectCreated信号：

QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, [&](QObject *obj, const QUrl &url) {
    if (!obj && url == QUrl("qrc:/main.qml")) {
        QCoreApplication::exit(-1);
    } else {
        // 从根对象开始递归查找
        QObject *root = engine.rootObjects().first();
        QList<QUIQImageItem*> items = root->findChildren<QUIQImageItem*>("liveImageItem");
        if (!items.isEmpty()) {
            auto imageItem = items.first();
            // 后续可以用imageItem调用setImage
        }
    }
});

2. 类型不匹配：你注册的类是QUIQImageItem，但查找时用的是ImageItem*——类型必须完全一致！把查找代码中的类型改成QUIQImageItem*就能解决这个问题。
3. 层级问题：直接调用engine->findChildren可能找不到嵌套在容器里的子项，先获取QML根对象，再从根对象开始查找就没问题了。

二、更可靠的方案：让QML主动传递引用

主动查找容易受加载时机、层级影响，不如让QML在加载完成后把ImageItem的引用直接传给C++类，步骤如下：

1. 定义一个负责更新图片的C++类：

class ImageUpdater : public QObject
{
    Q_OBJECT
public:
    explicit ImageUpdater(QObject *parent = nullptr) : QObject(parent) {}

    // 让QML调用这个方法传递ImageItem引用
    Q_INVOKABLE void setImageItem(QUIQImageItem *item) {
        m_imageItem = item;
    }

    // 当FileWatcher触发时，调用此方法更新图片
    void updateImage(const QImage &newImage) {
        if (m_imageItem) {
            m_imageItem->setImage(newImage);
        }
    }

private:
    QUIQImageItem *m_imageItem = nullptr;
};

2. 将这个类注册为QML上下文属性：

ImageUpdater updater;
engine.rootContext()->setContextProperty("imageUpdater", &updater);

3. 在QML的Component.onCompleted中传递引用：

Component.onCompleted: {
    imageUpdater.setImageItem(liveImageItem);
}

之后当FileWatcher检测到文件变化时，直接调用updater.updateImage(newImage)就能更新图片，完全不用手动查找，稳定性更高。

三、可选方案：使用Q_PROPERTY绑定

你的ImageItem已经有了image的读写方法和imageChanged信号，只需要添加Q_PROPERTY宏：

class QUIQImageItem : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QImage image READ image WRITE setImage NOTIFY imageChanged)
    // ... 其他代码
};

之后如果拿到了ImageItem的引用，可以直接通过setProperty设置图片：

imageItem->setProperty("image", newImage);

不过这种方式不如直接调用setImage类型安全，更推荐前两种方案。

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