QItemModelSurfaceDataProxy Class
代理类，用于在Q3DSurfaceWidgetItem 项目模型中显示数据。更多
| 头文件： | #include <QItemModelSurfaceDataProxy> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Graphs)target_link_libraries(mytarget PRIVATE Qt6::Graphs) |
| qmake： | QT += graphs |
| 在 QML 中： | ItemModelSurfaceDataProxy |
| 继承： | QSurfaceDataProxy |
- 所有成员的列表，包括继承成员
- QItemModelSurfaceDataProxy 是Qt Graphs C++ Classes for 3D 的一部分。
公共类型
| enum class | MultiMatchBehavior { First, Last, Average, CumulativeY } |
属性
|
|
公共功能
| QItemModelSurfaceDataProxy(QObject *parent = nullptr) | |
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr) | |
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &yPosRole, QObject *parent = nullptr) | |
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, QObject *parent = nullptr) | |
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, QObject *parent = nullptr) | |
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr) | |
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr) | |
| virtual | ~QItemModelSurfaceDataProxy() override |
| bool | autoColumnCategories() const |
| bool | autoRowCategories() const |
| QStringList | columnCategories() const |
| qsizetype | columnCategoryIndex(const QString &category) |
| QString | columnRole() const |
| QRegularExpression | columnRolePattern() const |
| QString | columnRoleReplace() const |
| QAbstractItemModel * | itemModel() const |
| QItemModelSurfaceDataProxy::MultiMatchBehavior | multiMatchBehavior() const |
| void | remap(const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories) |
| QStringList | rowCategories() const |
| qsizetype | rowCategoryIndex(const QString &category) |
| QString | rowRole() const |
| QRegularExpression | rowRolePattern() const |
| QString | rowRoleReplace() const |
| void | setAutoColumnCategories(bool enable) |
| void | setAutoRowCategories(bool enable) |
| void | setColumnCategories(const QStringList &categories) |
| void | setColumnRole(const QString &role) |
| void | setColumnRolePattern(const QRegularExpression &pattern) |
| void | setColumnRoleReplace(const QString &replace) |
| void | setItemModel(QAbstractItemModel *itemModel) |
| void | setMultiMatchBehavior(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior) |
| void | setRowCategories(const QStringList &categories) |
| void | setRowRole(const QString &role) |
| void | setRowRolePattern(const QRegularExpression &pattern) |
| void | setRowRoleReplace(const QString &replace) |
| void | setUseModelCategories(bool enable) |
| void | setXPosRole(const QString &role) |
| void | setXPosRolePattern(const QRegularExpression &pattern) |
| void | setXPosRoleReplace(const QString &replace) |
| void | setYPosRole(const QString &role) |
| void | setYPosRolePattern(const QRegularExpression &pattern) |
| void | setYPosRoleReplace(const QString &replace) |
| void | setZPosRole(const QString &role) |
| void | setZPosRolePattern(const QRegularExpression &pattern) |
| void | setZPosRoleReplace(const QString &replace) |
| bool | useModelCategories() const |
| QString | xPosRole() const |
| QRegularExpression | xPosRolePattern() const |
| QString | xPosRoleReplace() const |
| QString | yPosRole() const |
| QRegularExpression | yPosRolePattern() const |
| QString | yPosRoleReplace() const |
| QString | zPosRole() const |
| QRegularExpression | zPosRolePattern() const |
| QString | zPosRoleReplace() const |
信号
| void | autoColumnCategoriesChanged(bool enable) |
| void | autoRowCategoriesChanged(bool enable) |
| void | columnCategoriesChanged() |
| void | columnRoleChanged(const QString &role) |
| void | columnRolePatternChanged(const QRegularExpression &pattern) |
| void | columnRoleReplaceChanged(const QString &replace) |
| void | itemModelChanged(const QAbstractItemModel *itemModel) |
| void | multiMatchBehaviorChanged(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior) |
| void | rowCategoriesChanged() |
| void | rowRoleChanged(const QString &role) |
| void | rowRolePatternChanged(const QRegularExpression &pattern) |
| void | rowRoleReplaceChanged(const QString &replace) |
| void | useModelCategoriesChanged(bool enable) |
| void | xPosRoleChanged(const QString &role) |
| void | xPosRolePatternChanged(const QRegularExpression &pattern) |
| void | xPosRoleReplaceChanged(const QString &replace) |
| void | yPosRoleChanged(const QString &role) |
| void | yPosRolePatternChanged(const QRegularExpression &pattern) |
| void | yPosRoleReplaceChanged(const QString &replace) |
| void | zPosRoleChanged(const QString &role) |
| void | zPosRolePatternChanged(const QRegularExpression &pattern) |
| void | zPosRoleReplaceChanged(const QString &replace) |
详细说明
QItemModelSurfaceDataProxy 允许您使用QAbstractItemModel 派生模型作为Q3DSurfaceWidgetItem 的数据源。它使用定义的映射将数据从模型映射到Q3DSurfaceWidgetItem 图形的行、列和表面点。
每当映射或模型发生变化时，数据都会被异步解析。QSurfaceDataProxy::arrayReset(数据解析完成后，会发出（）。但是，当useModelCategories 属性设置为true 时，单个项目的变化会被同步解析，除非同一帧也包含导致整个模型被解析的变化。
可通过以下方式使用映射：
- 如果useModelCategories 属性设置为
true，该代理将把QAbstractItemModel 的行和列映射到Q3DSurfaceWidgetItem 的行和列，并默认使用Qt::DisplayRole 返回的值作为 Y 位置。如果行和列标题可以转换为浮点数，则默认将其用作 Z 位置和 X 位置。否则将使用行和列索引。如果Qt::DisplayRole 不合适，可以重新定义要使用的 Y 位置角色。如果标头或索引不合适，可以重新定义要使用的 Z 位置和 X 位置角色。 - 对于数据没有整齐地排序成行和列的模型，如基于QAbstractListModel 的模型，可以从模型中定义一个角色来映射每一行、每一列和每一个 Y 位置。
- 如果您不想包含模型中包含的所有数据，或者自动生成的行和列没有按您希望的顺序排列，您可以通过为行和列中的任一行或两行定义一个明确的类别列表来指定应包含哪些行和列以及它们的顺序。
例如，假设您有一个存储地表地形数据的自定义QAbstractItemModel 。模型中的每个项都具有 "经度"、"纬度 "和 "高度 "角色。项目模型已包含正确排序的数据，因此经度和纬度会以正确的顺序首先出现，这样我们就可以利用行和列类别自动生成功能。您可以采用以下方法在曲面图中显示数据：
QItemModelSurfaceDataProxy *proxy = new QItemModelSurfaceDataProxy(customModel, QStringLiteral("longitude"), // Row role QStringLiteral("latitude"), // Column role QStringLiteral("height")); // Y-position role
如果模型的字段不包含您所需的准确格式的数据，您可以为每个角色指定搜索模式正则表达式和替换规则，以获得您所需格式的值。有关使用正则表达式替换的工作原理，请参阅QString::replace(constQRegularExpression &rx, constQString &after)函数文档。请注意，使用正则表达式会影响性能，因此在不需要使用搜索和替换来获取所需数值的情况下，使用项目模型会更有效。
有关结合角色使用搜索模式的示例，请参阅ItemModelBarDataProxy 在简单条形图中的用法。
另请参阅 Qt Graphs 3D 数据处理。
成员类型文档
enum class QItemModelSurfaceDataProxy::MultiMatchBehavior
QItemModelSurfaceDataProxy::multiMatchBehavior 属性的行为类型。
| 常量 | 值 | 说明 |
|---|---|---|
QItemModelSurfaceDataProxy::MultiMatchBehavior::First | 0 | 位置值取自项目模型中与每个行/列组合匹配的第一个项目。 |
QItemModelSurfaceDataProxy::MultiMatchBehavior::Last | 1 | 位置值取自项目模型中与每个行/列组合匹配的最后一个项目。 |
QItemModelSurfaceDataProxy::MultiMatchBehavior::Average | 2 | 与每行/列组合相匹配的所有项目的位置值取平均值，然后将平均值用作表面点位置。 |
QItemModelSurfaceDataProxy::MultiMatchBehavior::CumulativeY | 3 | 对于 X 和 Z 值，其作用与Average 类似，但 Y 值是相加而不是平均，总和作为表面点 Y 位置。 |
属性文档
autoColumnCategories : bool
此属性表示是否自动生成列类别。
当设置为true 时，映射会忽略任何显式设置的列类别，并在解析模型数据时用自动生成的列类别覆盖它们。默认为true 。
访问功能：
| bool | autoColumnCategories() const |
| void | setAutoColumnCategories(bool enable) |
通知信号：
| void | autoColumnCategoriesChanged(bool enable) |
autoRowCategories : bool
此属性表示是否自动生成行类别。
当设置为true 时，映射会忽略任何显式设置的行类别，并在解析模型数据时用自动生成的类别覆盖它们。默认为true 。
访问功能：
| bool | autoRowCategories() const |
| void | setAutoRowCategories(bool enable) |
通知信号：
| void | autoRowCategoriesChanged(bool enable) |
columnCategories : QStringList
该属性包含映射的列类别。
访问功能：
| QStringList | columnCategories() const |
| void | setColumnCategories(const QStringList &categories) |
通知信号：
| void | columnCategoriesChanged() |
columnRole : QString
此属性包含映射到列类别的项目模型角色。
除了定义数据属于哪一列外，列角色指示的值还会在解析模型数据时设置为QSurfaceDataItem 的 X 坐标值，除非还定义了单独的 X 位置角色。
访问功能：
| QString | columnRole() const |
| void | setColumnRole(const QString &role) |
通知信号：
| void | columnRoleChanged(const QString &role) |
columnRolePattern : QRegularExpression
该属性用于确定是否在将列角色映射的值用作列类别之前对其进行搜索和替换。
该属性指定正则表达式，用于查找要替换的映射值部分，而columnRoleReplace 属性则包含替换字符串。
访问功能：
| QRegularExpression | columnRolePattern() const |
| void | setColumnRolePattern(const QRegularExpression &pattern) |
Notifier 信号：
| void | columnRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 columnRole 和columnRoleReplace 。
columnRoleReplace : QString
该属性包含与列角色模式一起使用的替换内容。
默认为空字符串。有关如何使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace(constQRegularExpression &rx, constQString &after)函数文档。
访问函数：
| QString | columnRoleReplace() const |
| void | setColumnRoleReplace(const QString &replace) |
Notifier 信号：
| void | columnRoleReplaceChanged(const QString &replace) |
另请参见 columnRole 和columnRolePattern 。
itemModel : QAbstractItemModel*
此属性包含用作 3D 曲面数据源的项目模型。
访问功能：
| QAbstractItemModel * | itemModel() const |
| void | setItemModel(QAbstractItemModel *itemModel) |
通知信号：
| void | itemModelChanged(const QAbstractItemModel *itemModel) |
multiMatchBehavior : QItemModelSurfaceDataProxy::MultiMatchBehavior
如何处理每行/列组合的多个匹配。
默认为最后一次。
例如，您可能有一个项目模型，其中的时间戳数据是以不规则的时间间隔采集的，您希望用曲面图直观显示数据项在每个小时的平均位置。为此，您可以指定行和列的类别，使每个曲面点代表一个小时，并将此属性设置为平均值。
访问功能：
| QItemModelSurfaceDataProxy::MultiMatchBehavior | multiMatchBehavior() const |
| void | setMultiMatchBehavior(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior) |
通知信号：
| void | multiMatchBehaviorChanged(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior) |
rowCategories : QStringList
该属性包含映射的行类别。
访问功能：
| QStringList | rowCategories() const |
| void | setRowCategories(const QStringList &categories) |
通知信号：
| void | rowCategoriesChanged() |
rowRole : QString
此属性包含映射到行类别的项目模型角色。
除了定义数据属于哪一行外，行角色指示的值还会在解析模型数据时设置为QSurfaceDataItem 的 Z 坐标值，除非还定义了单独的 Z 位置角色。
访问功能：
| QString | rowRole() const |
| void | setRowRole(const QString &role) |
通知信号：
| void | rowRoleChanged(const QString &role) |
rowRolePattern : QRegularExpression
该属性表示是否在行角色映射的值用作行类别之前对其执行搜索和替换。
该属性指定正则表达式，用于查找要替换的映射值部分，而rowRoleReplace 属性包含替换字符串。
访问功能：
| QRegularExpression | rowRolePattern() const |
| void | setRowRolePattern(const QRegularExpression &pattern) |
Notifier 信号：
| void | rowRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 rowRole 和rowRoleReplace 。
rowRoleReplace : QString
该属性包含与行角色模式一起使用的替换内容。
默认为空字符串。有关使用正则表达式进行搜索和替换的工作原理，请参阅QString::replace(constQRegularExpression &rx, constQString &after)函数文档。
访问函数：
| QString | rowRoleReplace() const |
| void | setRowRoleReplace(const QString &replace) |
Notifier 信号：
| void | rowRoleReplaceChanged(const QString &replace) |
另请参见 rowRole 和rowRolePattern 。
useModelCategories : bool
该属性用于确定是否在映射中使用行和列的角色和类别。
当设置为true 时，映射会忽略行和列的角色和类别，而使用模型中的行和列。默认值为false 。
访问功能：
| bool | useModelCategories() const |
| void | setUseModelCategories(bool enable) |
通知信号：
| void | useModelCategoriesChanged(bool enable) |
xPosRole : QString
该属性包含映射到 X 位置的项目模型角色。
如果未定义此角色，则columnRole 用于确定已解析的QSurfaceDataItem 对象的 X 坐标值。
访问功能：
| QString | xPosRole() const |
| void | setXPosRole(const QString &role) |
通知信号：
| void | xPosRoleChanged(const QString &role) |
xPosRolePattern : QRegularExpression
该属性用于确定是否在 x 位置角色映射的值用作项目位置值之前对其进行搜索和替换。
该属性指定正则表达式以查找要替换的映射值部分，xPosRoleReplace 属性包含替换字符串。
访问功能：
| QRegularExpression | xPosRolePattern() const |
| void | setXPosRolePattern(const QRegularExpression &pattern) |
Notifier 信号：
| void | xPosRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 xPosRole 和xPosRoleReplace 。
xPosRoleReplace : QString
该属性包含与 x 位置角色模式一起使用的替换内容。
默认为空字符串。有关如何使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。
访问函数：
| QString | xPosRoleReplace() const |
| void | setXPosRoleReplace(const QString &replace) |
Notifier 信号：
| void | xPosRoleReplaceChanged(const QString &replace) |
另请参见 xPosRole 和xPosRolePattern 。
yPosRole : QString
此属性包含映射到 Y 位置的项目模型角色。
访问功能：
| QString | yPosRole() const |
| void | setYPosRole(const QString &role) |
通知信号：
| void | yPosRoleChanged(const QString &role) |
yPosRolePattern : QRegularExpression
该属性用于确定是否在 y 位置角色映射的值用作项目位置值之前对其进行搜索和替换。
该属性指定正则表达式以查找要替换的映射值部分，yPosRoleReplace 属性包含替换字符串。
访问功能：
| QRegularExpression | yPosRolePattern() const |
| void | setYPosRolePattern(const QRegularExpression &pattern) |
Notifier 信号：
| void | yPosRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 yPosRole 和yPosRoleReplace 。
yPosRoleReplace : QString
该属性包含与 Y 位置角色模式一起使用的替换内容。
默认为空字符串。有关如何使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。
访问函数：
| QString | yPosRoleReplace() const |
| void | setYPosRoleReplace(const QString &replace) |
Notifier 信号：
| void | yPosRoleReplaceChanged(const QString &replace) |
另请参见 yPosRole 和yPosRolePattern 。
zPosRole : QString
该属性包含映射到 Z 位置的项目模型角色。
如果未定义此角色，则rowRole 用于确定已解析QSurfaceDataItem 对象的 Z 坐标值。
访问功能：
| QString | zPosRole() const |
| void | setZPosRole(const QString &role) |
通知信号：
| void | zPosRoleChanged(const QString &role) |
zPosRolePattern : QRegularExpression
该属性用于确定是否在将 z 位置角色映射的值用作项目位置值之前对其进行搜索和替换。
该属性指定正则表达式以查找要替换的映射值部分，zPosRoleReplace 属性包含替换字符串。
访问功能：
| QRegularExpression | zPosRolePattern() const |
| void | setZPosRolePattern(const QRegularExpression &pattern) |
Notifier 信号：
| void | zPosRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 zPosRole 和zPosRoleReplace 。
zPosRoleReplace : QString
该属性包含与 z 位置角色模式一起使用的替换内容。
默认为空字符串。有关使用正则表达式进行搜索和替换的工作原理，请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。
访问函数：
| QString | zPosRoleReplace() const |
| void | setZPosRoleReplace(const QString &replace) |
Notifier 信号：
| void | zPosRoleReplaceChanged(const QString &replace) |
另请参见 zPosRole 和zPosRolePattern 。
成员函数文档
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QObject *parent = nullptr)
构造带有可选parent 的 QItemModelSurfaceDataProxy。
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr)
用itemModel 和一个可选的parent 构造 QItemModelSurfaceDataProxy。该代理不拥有itemModel 的所有权，因为项目模型通常由其他控件拥有。
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &yPosRole, QObject *parent = nullptr)
用itemModel 和一个可选的parent 构造 QItemModelSurfaceDataProxy。该代理并不拥有itemModel 的所有权，因为通常项目模型是由其他控件拥有的。yPosRole 角色被设置为yPosRole 。该构造函数的目的是与已按行和列正确排序数据的模型一起使用，因此它还将useModelCategories 属性设置为true 。
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, QObject *parent = nullptr)
用itemModel 和一个可选的parent 构造 QItemModelSurfaceDataProxy。该代理不拥有itemModel 的所有权，因为项目模型通常由其他控件拥有。角色映射是通过rowRole 、columnRole 和yPosRole 设置的。zPosRole 和xPosRole 分别设置为rowRole 和columnRole 。
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, QObject *parent = nullptr)
用itemModel 和一个可选的parent 构造 QItemModelSurfaceDataProxy。该代理不拥有itemModel 的所有权，因为项目模型通常由其他控件拥有。角色映射由rowRole,columnRole,xPosRole,yPosRole 和zPosRole 设置。
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)
用itemModel 和一个可选的parent 构造 QItemModelSurfaceDataProxy。该代理不拥有itemModel 的所有权，因为项目模型通常由其他控件拥有。角色映射是通过rowRole 、columnRole 和yPosRole 设置的。zPosRole 和xPosRole 分别设置为rowRole 和columnRole 。行和列类别通过rowCategories 和columnCategories 设置。此构造函数还将autoRowCategories 和autoColumnCategories 设置为 false。
[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)
用itemModel 和一个可选的parent 构造 QItemModelSurfaceDataProxy。该代理不拥有itemModel 的所有权，因为项目模型通常由其他控件拥有。角色映射是通过rowRole,columnRole,xPosRole,yPosRole 和zPosRole 设置的。行和列类别通过rowCategories 和columnCategories 设置。此构造函数还将autoRowCategories 和autoColumnCategories 设置为 false。
[override virtual noexcept] QItemModelSurfaceDataProxy::~QItemModelSurfaceDataProxy()
销毁QItemModelSurfaceDataProxy 。
[invokable] qsizetype QItemModelSurfaceDataProxy::columnCategoryIndex(const QString &category)
返回指定category 在列类别列表中的索引。如果未找到类别，则返回-1。
注： 如果使用了自动生成列类别的功能，在第一次解析模型中的数据之前，此方法不会返回有效的索引。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
void QItemModelSurfaceDataProxy::remap(const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories)
更改rowRole,columnRole,xPosRole,yPosRole,zPosRole,rowCategories 和columnCategories 的映射。
[invokable] qsizetype QItemModelSurfaceDataProxy::rowCategoryIndex(const QString &category)
返回指定category 在行类别列表中的索引。如果行类别列表为空，则返回-1。
注： 如果正在使用自动行类别生成功能，则在首次解析模型中的数据之前，此方法不会返回有效索引。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
void QItemModelSurfaceDataProxy::setItemModel(QAbstractItemModel *itemModel)
将项目模型设置为itemModel 。不拥有模型的所有权，但会连接到模型以监听更改。
注： 属性itemModel 的设置函数。
另请参阅 itemModel().
© 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.
