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)

附加信号

与附加属性类似，附加信号允许类型为对象提供额外的信号处理器。这些信号通常用于生命周期事件。

例如，组件类型就提供了附加信号：

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'sisCurrentItem)
属性在逻辑上属于容器或上下文，而不是项目本身
你想避免用特殊属性使基本类型杂乱无章

另请参阅 QML Object Types（QML 对象类型）、The QML Type System（QML 类型系统）和Defining QML Types from C++（从 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.