QQmlListProperty Class
template <typename T> class QQmlListPropertyQQmlListProperty 类允许应用程序将QObject 派生类的列表样式属性暴露给 QML。更多内容...
| 头文件： | #include <QQmlListProperty> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake： | QT += qml |
公共类型
公共函数
| QQmlListProperty(QObject *object, QList<T *> *list) | |
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at) | |
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear) | |
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear, QQmlListProperty<T>::ReplaceFunction replace, QQmlListProperty<T>::RemoveLastFunction removeLast) | |
| bool | operator==(const QQmlListProperty<T> &other) const |
公共变量
宏
| QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND | |
| QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE | |
| QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT |
详细说明
QML 拥有许多列表属性，这些属性可以被赋予多个对象值。在 QML 中使用列表属性的方式如下：
FruitBasket {
fruit: [
Apple {},
Orange{},
Banana{}
]
}QQmlListProperty 封装了一组函数指针，这些指针代表 QML 可以对列表执行的一系列操作——添加项目、检索项目以及清空列表。未来可能会支持更多操作。所有列表属性都必须实现 append 操作，但其余操作均为可选。
要提供列表属性，C++ 类必须实现操作回调，然后通过属性的 getter 方法返回相应的 QQmlListProperty 值。列表属性不应具有 setter 方法。在上例中，Q_PROPERTY() 的声明形式如下：
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)QML 列表属性是类型安全的。模板参数T 指定了可以存储在列表中的QObject 派生类型。在此示例中，Fruit 是一个QObject 类型，Apple 、Orange 和Banana 均从此类型派生而来。
您可以使用QQmlListReference 通过略微更人性化的 API 从 C++ 操作 QQmlListProperty，但会带来一些开销。
另请参阅 第 5 章：使用列表属性类型以及QQmlListReference 。
成员类型文档
[alias] QQmlListProperty::AppendFunction
void (*)(QQmlListProperty<T> *property, T *value) 的同义词。
将value 追加到列表property 中。
[alias] QQmlListProperty::AtFunction
T *(*)(QQmlListProperty<T> *property, qsizetype index) 的同义词。
返回列表property 中位于位置index 的元素。
[alias] QQmlListProperty::ClearFunction
void (*)(QQmlListProperty<T> *property) 的同义词。
清空列表property 。
[alias] QQmlListProperty::CountFunction
qsizetype (*)(QQmlListProperty<T> *property) 的同义词。
返回列表property 中的元素个数。
[alias] QQmlListProperty::RemoveLastFunction
void (*)(QQmlListProperty<T> *property) 的同义词。
从列表property 中移除最后一个元素。
[alias] QQmlListProperty::ReplaceFunction
void (*)(QQmlListProperty<T> *property, qsizetype index, T *value) 的同义词。
将列表property 中位于位置index 的元素替换为value 。
成员函数文档
QQmlListProperty::QQmlListProperty(QObject *object, QList<T *> *list)
一个便捷构造函数，用于从现有的QList （list ）创建QQmlListProperty的值。必须提供拥有该列表的object 以及list 本身，并且只要您持有引用它们的QQmlListProperty，就必须保持它们存活。
这是提供由QList 支持的QQmlListProperty最简单、最安全的方法，在大多数情况下都应使用此方法。典型的调用方式如下：
QQmlListProperty<PieSlice> PieChart::slices()
{
return QQmlListProperty<PieSlice>(this, &m_slices);
}QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at)
根据一组操作函数count 和at 构建一个只读的QQmlListProperty。可以传递一个不透明的data 句柄，该句柄可在操作函数内部进行访问。只要拥有该列表属性的object 仍然存在，该列表属性就保持有效。
QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear)
根据一组操作函数append 、count 、at 和clear 构建一个QQmlListProperty。可以传递一个不透明的data 句柄，该句柄可在操作函数内部被访问。只要拥有该列表属性的object 对象存在，该列表属性就保持有效。
任何函数均可传入空指针。若传入任何空指针，列表将无法被调试器设计或修改。建议为所有函数提供有效的指针。
注意：生成的 QQmlListProperty 将使用count 、at 、clear 和append 来合成 removeLast() 和 replace() 方法（前提是这些方法均已提供）。此过程速度较慢。若您计划对列表进行清空以外的操作，应显式提供这些方法。
QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear, QQmlListProperty<T>::ReplaceFunction replace, QQmlListProperty<T>::RemoveLastFunction removeLast)
根据一组操作函数append 、count 、at 、clear 、replace 和removeLast 构建一个QQmlListProperty。可以传递一个不透明的data 句柄，该句柄可在操作函数内部进行访问。只要拥有该列表属性的object 仍然存在，该列表属性就保持有效。
任何函数均可传递空指针，这将导致相应函数在可能的情况下通过其他函数进行合成。QQmlListProperty 可通过
- clear 使用count 以及removeLast
- replace 使用count 、at 、clear 进行合成，以及append
- replace count 、 、 ，以及at removeLast append
- removeLast 使用count 、at 、clear ，以及append
（如果这些参数已提供）。虽然这种方式较慢，但如果您的列表本身未针对这些基本操作提供更快的原生选项，您可能需要使用这些合成方法。
此外，如果count 、at 、append 和clear 均未被显式提供或合成，则该列表将无法被调试器设计或修改。建议提供足够数量的有效指针以避免这种情况。
bool QQmlListProperty::operator==(const QQmlListProperty<T> &other) const
如果该QQmlListProperty 等于other ，则返回true；否则返回false。
成员变量文档
void *QQmlListProperty::data
该字段可存储任意数据指针
如果您手动实现了访问器方法且需要存储自定义数据，可以将任意指针传递给 `QQmlListProperty ` 构造函数，并在后续访问同一 `QQmlListProperty ` 时从数据字段中检索该指针。
QQmlListProperty constructed from a QList pointer 类使用该字段来存储指向列表本身的指针，因为它无法直接从所有者处访问列表内容。
QObject *QQmlListProperty::object
该字段存储QQmlListProperty
在手动实现访问器方法时，您可能需要使用此字段来检索被操作列表的内容。
宏文档
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
该宏将本类的列表属性行为定义为“追加”（Append）。在派生类型中赋值时，这些值将被追加到基类的值之后。这是默认行为。
class FruitBasket : QObject {
Q_OBJECT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
public:
// ...
QQmlListProperty<Fruit> fruit();
// ...
};另请参阅 QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT 、QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE 以及《通过 QML 文档定义对象类型》。
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
该宏将此类的列表属性行为定义为“替换”。在派生类型中设置该属性时，其值将替换基类的值。
class FruitBasket : QObject {
Q_OBJECT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
public:
// ...
QQmlListProperty<Fruit> fruit();
// ...
};另请参阅 QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND 、QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT 以及《通过 QML 文档定义对象类型》。
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT
该宏将此类列表属性的行为定义为“ReplaceIfNotDefault”。在派生类型中为该属性赋值时，除非是默认属性，否则新值将替换基类的值；如果是默认属性，则新值将附加到基类的值之后。
class FruitBasket : QObject {
Q_OBJECT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
public:
// ...
QQmlListProperty<Fruit> fruit();
// ...
};另请参阅 QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND 、QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE 以及《通过 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.
