Back to Qt.io
Contact Us Blog Download Qt
本页内容

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

公共类型

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::First0位置值取自项目模型中与每行/列组合相匹配的第一个项目。
QItemModelSurfaceDataProxy::MultiMatchBehavior::Last1位置值取自项目模型中与每个行/列组合相匹配的最后一个项目。
QItemModelSurfaceDataProxy::MultiMatchBehavior::Average2将匹配每个行/列组合的所有项目的位置值进行平均，并将平均值用作表面点位置。
QItemModelSurfaceDataProxy::MultiMatchBehavior::CumulativeY3对于 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-position角色。

访问函数：

QString columnRole() const
void setColumnRole(const QString &role)

通知信号：

void columnRoleChanged(const QString &role)

columnRolePattern : QRegularExpression

该属性用于指定在将列角色映射的值用作列类别之前，是否对其进行搜索和替换操作。

该属性指定用于查找映射值中待替换部分的正则表达式，而columnRoleReplace 属性则包含替换字符串。

访问函数：

QRegularExpression columnRolePattern() const
void setColumnRolePattern(const QRegularExpression &pattern)

通知信号：

void columnRolePatternChanged(const QRegularExpression &pattern)

另请参阅 columnRole 和columnRoleReplace 。

columnRoleReplace : QString

此属性存储与列角色模式配合使用的替换内容。

默认值为空字符串。有关使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace （constQRegularExpression &rx, constQString &after）函数的文档。

访问函数：

QString columnRoleReplace() const
void setColumnRoleReplace(const QString &replace)

通知器信号：

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-position角色。

访问函数：

QString rowRole() const
void setRowRole(const QString &role)

通知信号：

void rowRoleChanged(const QString &role)

rowRolePattern : QRegularExpression

该属性用于指定在将行角色映射的值用作行类别之前，是否对其进行搜索和替换操作。

该属性指定用于查找映射值中待替换部分的正则表达式，而rowRoleReplace 属性则包含替换字符串。

访问函数：

QRegularExpression rowRolePattern() const
void setRowRolePattern(const QRegularExpression &pattern)

通知信号：

void rowRolePatternChanged(const QRegularExpression &pattern)

另请参阅 rowRole 和rowRoleReplace 。

rowRoleReplace : QString

该属性保存与行角色模式配合使用的替换内容。

默认值为空字符串。有关使用正则表达式进行搜索和替换的详细信息，请参阅QString::replace （constQRegularExpression &rx, constQString &after）函数文档。

访问函数：

QString rowRoleReplace() const
void setRowRoleReplace(const QString &replace)

通知器信号：

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)

通知信号：

void xPosRolePatternChanged(const QRegularExpression &pattern)

另请参阅 xPosRole 和xPosRoleReplace 。

xPosRoleReplace : QString

该属性存储将与 x 位置角色模式配合使用的替换内容。

默认值为空字符串。有关使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace （constQRegularExpression &rx, constQString &after）函数的文档。

访问函数：

QString xPosRoleReplace() const
void setXPosRoleReplace(const QString &replace)

通知器信号：

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)

通知信号：

void yPosRolePatternChanged(const QRegularExpression &pattern)

另请参阅 yPosRole 和yPosRoleReplace 。

yPosRoleReplace : QString

该属性存储与 y 位置角色模式配合使用的替换内容。

默认值为空字符串。有关使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace （constQRegularExpression &rx, constQString &after）函数的文档。

访问函数：

QString yPosRoleReplace() const
void setYPosRoleReplace(const QString &replace)

通知器信号：

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)

通知信号：

void zPosRolePatternChanged(const QRegularExpression &pattern)

另请参阅 zPosRole 和zPosRoleReplace 。

zPosRoleReplace : QString

该属性存储将与 z 位置角色模式配合使用的替换内容。

默认值为空字符串。有关使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace （constQRegularExpression &rx, constQString &after）函数的文档。

访问函数：

QString zPosRoleReplace() const
void setZPosRoleReplace(const QString &replace)

通知器信号：

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()。

© 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.