QQmlListProperty Class
template <typename T> class QQmlListPropertyQQmlListProperty 类允许应用程序向 QML 公开QObject 派生类的列表式属性。更多
| Header： | #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++ 类必须实现操作回调，然后从属性获取器返回一个适当的 QQmlListProperty 值。列表属性不应有设置器。在上面的示例中，Q_PROPERTY() 声明将如下所示：
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
QML 列表属性是类型安全的--在本例中，Fruit 是QObject 类型，Apple 、Orange 和Banana 都派生自该类型。
您可以使用QQmlListReference 来操作 C++ 中的 QQmlListProperty，使用的 API 更符合人体工程学，但代价是一些开销。
另请参见 第 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) 的同义词。
用value 替换列表property 中位于index 位置的元素。
成员函数文档
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 文档定义对象类型。
© 2025 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.
