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.