QMLの付加型

アタッチドプロパティおよびシグナルは、オブジェクトに、その基底型には含まれていない追加のプロパティやシグナルを付与するための仕組みです。アタッチドプロパティへのアクセスは、そのプロパティを提供する型を識別する名前空間付き構文を通じて行われます。

概要

一部の型には、他のオブジェクトにアタッチできるプロパティやシグナルがあり、継承を必要とせずに追加の機能を提供します。アタッチされたプロパティやシグナルには、プロパティ名またはシグナル名の先頭に、それをアタッチする型の名前を付けることでアクセスします。

たとえば、ListView 型にはisCurrentItem というアタッチされたプロパティがあり、ListView のデリゲート内の任意のアイテムからアクセスできます。

ListView {
    width: 240
    height: 320
    model: 3
    delegate: Rectangle {
        width: 100
        height: 30
        color: ListView.isCurrentItem ? "red" : "yellow"
    }
}

ここで、ListView.isCurrentItem は、ListView によって各デリゲート・アイテムで利用可能になるアタッチド・プロパティです。

アタッチドプロパティ

アタッチドプロパティを使用すると、ベース型によって定義されているオブジェクトにプロパティを追加することができます。プロパティの値はオブジェクトの外部に格納され、アタッチ元となる型の名前を通じてアクセスされます。

一般的な例としては、次のようなものがあります:

ListView アタッチドプロパティ（isCurrentItem 、view ）
GridView アタッチドプロパティ
Keys キーボードイベント処理用のアタッチドプロパティ
Component アタッチドプロパティ (onCompleted,onDestruction)

アタッチドシグナル

アタッチされたプロパティと同様に、アタッチされたシグナルを使用すると、型がオブジェクトに追加のシグナルハンドラを提供できるようになります。これらは一般的にライフサイクルイベントに使用されます。

たとえば、Component型は次のようなアタッチドシグナルを提供しています：

Rectangle {
    Component.onCompleted: {
        console.log("Rectangle creation completed")
    }

    Component.onDestruction: {
        console.log("Rectangle is being destroyed")
    }
}

C++でのアタッチドプロパティの作成

C++ から独自の型用のアタッチドプロパティを作成するには、次の手順を実行する必要があります：

以下から派生したアタッチドプロパティクラスを作成しますQObject
このクラスでアタッチドプロパティを実装する
メインの型にQML_ATTACHED マクロを追加する
静的なqmlAttachedProperties() メソッドを実装する

例:

class MyAttachedType : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
    QML_ANONYMOUS

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

    int value() const { return m_value; }
    void setValue(int value)
    {
        if (m_value != value) {
            m_value = value;
            emit valueChanged();
        }
    }

signals:
    void valueChanged();

private:
    int m_value = 0;
};

class MyType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_ATTACHED(MyAttachedType)

public:
    static MyAttachedType *qmlAttachedProperties(QObject *object)
    {
        return new MyAttachedType(object);
    }
};

QMLでの使用方法：

Item {
    MyType.value: 42
}

アタッチする型（この場合はMyType ）が、他のオブジェクトにプロパティをアタッチすることしか行わない場合は、これを単一のクラスとして記述できます:

class MyType : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
    QML_ELEMENT
    QML_ATTACHED(MyType)

public:
    static MyType *qmlAttachedProperties(QObject *object)
    {
        return new MyType(object);
    }

    MyType(QObject *parent = nullptr) : QObject(parent) {}

    int value() const { return m_value; }
    void setValue(int value)
    {
        if (m_value != value) {
            m_value = value;
            emit valueChanged();
        }
    }

signals:
    void valueChanged();

private:
    int m_value = 0;
};

アタッチドプロパティの使用場面

アタッチドプロパティは、次のような場合に役立ちます：

アイテムにコンテキスト固有の情報を追加したい場合（ListView のisCurrentItem など）
プロパティが、アイテム自体ではなく、論理的にはコンテナやコンテキストに属する場合
基底型を特殊なプロパティで煩雑にしたくない場合

「QML オブジェクト型」、「QML 型システム」、「C++ からの QML 型の定義」も参照してください 。

QML におけるシングルトン QML ネームスペース

© 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.