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.