C++からQMLへの状態の公開

C++のプロパティを、特定のコンポーネント内のすべてのQML要素、モジュール内のすべてのQML要素、あるいはQML全体にわたるすべてのQML要素に対して公開したい場合がよくあります。これを行うには、シングルトンを導入するか、特定のコンポーネントのルートオブジェクトにプロパティを追加します。

シングルトンの使用

モジュール内のすべての要素や、すべてのQML要素に対して複数のグローバルプロパティを公開したい場合は、C++でシングルトンを定義できます。これを行うには、公開したいプロパティをQ_PROPERTY 宣言として含むクラスに、QML_ELEMENT またはQML_NAMED_ELEMENT マクロ、およびQML_SINGLETONマクロを追加します。

// Singleton.h
class Singleton : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int thing READ thing WRITE setThing NOTIFY thingChanged FINAL)
    QML_ELEMENT
    QML_SINGLETON

public:
    Singleton(QObject *parent = nullptr) : QObject(parent) {}

    int thing() const { return m_value; }
    void setThing(int v)
    {
        if (v != m_value) {
            m_value = v;
            emit thingChanged();
        }
    }

signals:
    void thingChanged();

private:
    int m_value = 12;
};

これで、このモジュールをインポートする任意の QML コードから、シングルトンの`thing`プロパティにアクセスできるようになります:

import QtQml

QtObject {
    objectName: "The thing is " + Singleton.thing
}

QMLファイルをモジュールと同じディレクトリに配置している場合（強く推奨されます）、モジュール内の暗黙的なインポートを通じてシングルトンを利用できます。明示的にインポートする必要はありません。そうでない場合、または他のモジュールから`thing`プロパティにアクセスしたい場合は、シングルトンが属するモジュールをインポートする必要があります。

C++からプロパティの値を設定するには、シングルトンのインスタンスを取得する必要がある場合があります。この目的には、QQmlEngine::singletonInstance を使用できます。これを行う推奨される方法は、モジュール名と型名をパラメータとして指定することです：

    Singleton *singleton
            = engine->singletonInstance<Singleton *>("MyModule", "Singleton");
    singleton->setThing(77);

オブジェクトのプロパティの使用

特定コンポーネント内のQML要素に対してのみプロパティを公開したい場合は、それらをコンポーネントのルートオブジェクトに通常のプロパティとして追加できます。あらゆるケースで確実に設定されるようにするには、それらを必須プロパティにすることができます。QMLコンポーネントは次のように記述できます：

pragma ComponentBehavior: Bound

import QtQuick

Window {
    id: root
    visible: true

    required property int thing

    Text {
        anchors.fill: parent
        text: "The thing is " + root.thing
    }

    component Inner: QtObject {
        objectName: "I can see " + root.thing + " because I'm bound."
    }
}

コンポーネントのルート要素にはIDを使用し、内部のオブジェクトからはIDと名前でプロパティを参照します。ネストされたコンポーネントからルート要素のIDを安全に利用できるようにするため、ComponentBehaviorを使用します。

その後、C++でそのようなコンポーネントからオブジェクトを作成する際は、プロパティを初期化するために、QQmlComponent::createWithInitialProperties 、QQmlApplicationEngine::setInitialProperties 、またはQQuickView::setInitialProperties を必ず呼び出す必要があります。例えば：

    QQmlEngine engine;

    QQmlComponent component(&engine, "MyModule", "RequiredProperties");
    QScopedPointer<QObject> o(component.createWithInitialProperties({
            {"thing", 11}
    }));

これは、モジュール URI がMyModuleであり、そのモジュールが QML のインポートパス上に存在することを前提としています。

C++ 型の属性を QML に公開する CMake を使ってすべてを統合する

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.