QML 付属型

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

概要

いくつかの型は、他のオブジェクトにアタッチできるプロパティやシグナルを持ち、継承を必要とせずに追加機能を提供します。アタッチされたプロパティやシグナルにアクセスするには、プロパティ名やシグナル名の前にアタッチする型の名前を付けます。

例えば、ListView 型にはisCurrentItem というアタッチド・プロパティがあり、ListView's delegate 内のどのアイテムにもアクセスできます：

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.