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 네임스페이스

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