QItemModelBarDataProxy Class

代理类,用于在Q3DBarsWidgetItem 项目模型中显示数据。更多

头文件: #include <QItemModelBarDataProxy>
CMake: find_package(Qt6 REQUIRED COMPONENTS Graphs)
target_link_libraries(mytarget PRIVATE Qt6::Graphs)
qmake: QT += graphs
在 QML 中: ItemModelBarDataProxy
继承: QBarDataProxy

公共类型

enum class MultiMatchBehavior { First, Last, Average, Cumulative }

属性

公共功能

QItemModelBarDataProxy(QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &valueRole, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)
virtual ~QItemModelBarDataProxy() 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
QItemModelBarDataProxy::MultiMatchBehavior multiMatchBehavior() const
void remap(const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories)
QString rotationRole() const
QRegularExpression rotationRolePattern() const
QString rotationRoleReplace() const
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(QItemModelBarDataProxy::MultiMatchBehavior behavior)
void setRotationRole(const QString &role)
void setRotationRolePattern(const QRegularExpression &pattern)
void setRotationRoleReplace(const QString &replace)
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 setValueRole(const QString &role)
void setValueRolePattern(const QRegularExpression &pattern)
void setValueRoleReplace(const QString &replace)
bool useModelCategories() const
QString valueRole() const
QRegularExpression valueRolePattern() const
QString valueRoleReplace() 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(QItemModelBarDataProxy::MultiMatchBehavior behavior)
void rotationRoleChanged(const QString &role)
void rotationRolePatternChanged(const QRegularExpression &pattern)
void rotationRoleReplaceChanged(const QString &replace)
void rowCategoriesChanged()
void rowRoleChanged(const QString &role)
void rowRolePatternChanged(const QRegularExpression &pattern)
void rowRoleReplaceChanged(const QString &replace)
void useModelCategoriesChanged(bool enable)
void valueRoleChanged(const QString &role)
void valueRolePatternChanged(const QRegularExpression &pattern)
void valueRoleReplaceChanged(const QString &replace)

详细说明

QItemModelBarDataProxy 允许您使用QAbstractItemModel 派生模型作为Q3DBarsWidgetItem 的数据源。它使用定义的映射将模型中的数据映射到Q3DBarsWidgetItem 图形的行、列和值。

每当映射或模型发生变化时,数据都会被异步解析。QBarDataProxy::arrayReset(数据解析完成后,会发出()。但是,当useModelCategories 属性设置为 true 时,单个项目的更改会同步解析,除非同一帧也包含导致整个模型解析的更改。

可通过以下方式使用映射:

  • 如果useModelCategories 属性设置为 true,此代理会将QAbstractItemModel 的行和列直接映射到Q3DBarsWidgetItem 的行和列,并默认使用Qt::DisplayRole 返回的值作为栏值。如果Qt::DisplayRole 不合适,可以重新定义要使用的值角色。
  • 对于没有将数据整齐地排序到行和列的模型,如基于QAbstractListModel 的模型,可以从模型中定义一个角色来映射每一行、列和值。
  • 如果您不想包含模型中包含的所有数据,或者自动生成的行和列没有按您希望的顺序排列,您可以通过为行和列中的某一行或两行定义一个明确的类别列表来指定应包含哪些行和列以及它们的顺序。

例如,假设您有一个自定义QAbstractItemModel ,用于存储与业务相关的各种月度值。模型中的每个项目都有 "年"、"月"、"收入 "和 "支出 "等角色。您可以采用以下方法在条形图中显示数据:

// By defining row and column categories, you tell the mapping which row and column each item
// belongs to. The categories must match the data stored in the model in the roles you define
// for row and column mapping. In this example we expect "year" role to return four digit year
// and "month" to return three letter designation for the month.
//
// An example of an item in model would be:
// Requested role -> Returned data
// "year" -> "2016" // Matches the first row category, so this item is added to the first row.
// "month" -> "jan" // Matches the first column category, so this item is added as first item in the row.
// "income" -> "12.1"
// "expenses" -> "9.2"
QStringList years;
QStringList months;
years << "2016" << "2017" << "2018" << "2019" << "2020" << "2021" << "2022";
months << "jan" << "feb" << "mar" << "apr" << "may" << "jun" << "jul" << "aug" << "sep" << "oct" << "nov" << "dec";

QItemModelBarDataProxy *proxy = new QItemModelBarDataProxy(customModel,
                                                           QStringLiteral("year"), // Row role
                                                           QStringLiteral("month"), // Column role
                                                           QStringLiteral("income"), // Value role
                                                           years, // Row categories
                                                           months); // Column categories

//...

// To display different data later, you can simply change the mapping.
proxy->setValueRole(QStringLiteral("expenses"));

如果模型的字段不包含所需格式的数据,可以为每个角色指定搜索模式正则表达式和替换规则,以获得所需格式的值。有关使用正则表达式替换的工作原理,请参阅QString::replace(constQRegularExpression &rx, constQString &after)函数文档。请注意,使用正则表达式会影响性能,因此在不需要使用搜索和替换来获取所需数值的情况下,使用项目模型会更有效。

有关结合角色使用搜索模式的示例,请参阅简单条形图

另请参阅 Qt Graphs 3D 数据处理

成员类型文档

enum class QItemModelBarDataProxy::MultiMatchBehavior

QItemModelBarDataProxy::multiMatchBehavior 属性的行为类型。

常量说明
QItemModelBarDataProxy::MultiMatchBehavior::First0该值取自项目模型中与每个行/列组合匹配的第一个项目。
QItemModelBarDataProxy::MultiMatchBehavior::Last1取自项目模型中与每个行/列组合匹配的最后一个项目的值。
QItemModelBarDataProxy::MultiMatchBehavior::Average2将与每行/列组合匹配的所有项目的值取平均值,并将平均值作为条形图值。
QItemModelBarDataProxy::MultiMatchBehavior::Cumulative3将与每个行/列组合匹配的所有项目的值相加,然后将总值用作条形图值。

属性文档

autoColumnCategories : bool

此属性表示是否自动生成列类别。

当设置为true 时,映射会忽略任何显式设置的列类别,并在解析来自模型的数据时用自动生成的列类别覆盖它们。默认为true

访问功能:

bool autoColumnCategories() const
void setAutoColumnCategories(bool enable)

Notifier 信号:

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

该属性包含映射的列角色。

访问功能:

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)

另请参阅 columnRolecolumnRoleReplace

columnRoleReplace : QString

该属性包含与columnRolePattern 一起使用的替换内容。

默认为空字符串。有关使用正则表达式进行搜索和替换的工作原理,请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。

访问函数:

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

Notifier 信号:

void columnRoleReplaceChanged(const QString &replace)

另请参见 columnRolecolumnRolePattern

itemModel : QAbstractItemModel*

此属性包含项目模型。

访问功能:

QAbstractItemModel *itemModel() const
void setItemModel(QAbstractItemModel *itemModel)

通知信号:

void itemModelChanged(const QAbstractItemModel *itemModel)

multiMatchBehavior : QItemModelBarDataProxy::MultiMatchBehavior

如何处理每行/列组合的多个匹配项。

默认为QItemModelBarDataProxy::MultiMatchBehavior::Last 。所选行为会影响条形图的值和旋转。

例如,您可能有一个带有时间戳数据的项目模型,这些数据是以不规则的时间间隔采集的,您希望用柱形图直观地显示数据项在每一天的总价值。为此,您可以指定行和列的类别,使每个条形图代表一天,并将 multiMatchBehavior 设置为QItemModelBarDataProxy::MultiMatchBehavior::Cumulative

访问功能:

QItemModelBarDataProxy::MultiMatchBehavior multiMatchBehavior() const
void setMultiMatchBehavior(QItemModelBarDataProxy::MultiMatchBehavior behavior)

通知信号:

void multiMatchBehaviorChanged(QItemModelBarDataProxy::MultiMatchBehavior behavior)

rotationRole : QString

该属性用于保存映射的旋转角色。

访问功能:

QString rotationRole() const
void setRotationRole(const QString &role)

通知信号:

void rotationRoleChanged(const QString &role)

rotationRolePattern : QRegularExpression

该属性表示是否在旋转角色映射的值用作条形图旋转角度之前对其进行搜索和替换。

该属性指定正则表达式,用于查找要替换的映射值部分,rotationRoleReplace 属性包含替换字符串。

访问功能:

QRegularExpression rotationRolePattern() const
void setRotationRolePattern(const QRegularExpression &pattern)

Notifier 信号:

void rotationRolePatternChanged(const QRegularExpression &pattern)

另请参阅 rotationRolerotationRoleReplace

rotationRoleReplace : QString

该属性包含与rotationRolePattern 一起使用的替换内容。

默认为空字符串。有关使用正则表达式进行搜索和替换的工作原理,请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。

访问函数:

QString rotationRoleReplace() const
void setRotationRoleReplace(const QString &replace)

Notifier 信号:

void rotationRoleReplaceChanged(const QString &replace)

另请参见 rotationRolerotationRolePattern

rowCategories : QStringList

该属性包含映射的行类别。

访问功能:

QStringList rowCategories() const
void setRowCategories(const QStringList &categories)

通知信号:

void rowCategoriesChanged()

rowRole : QString

该属性包含映射的行角色。

访问功能:

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)

另请参阅 rowRolerowRoleReplace

rowRoleReplace : QString

该属性包含与rowRolePattern 一起使用的替换内容。

默认为空字符串。有关使用正则表达式进行搜索和替换的工作原理,请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。

访问函数:

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

Notifier 信号:

void rowRoleReplaceChanged(const QString &replace)

另请参见 rowRolerowRolePattern

useModelCategories : bool

该属性用于确定是否在映射中使用行和列的角色和类别。

当设置为true 时,映射会忽略行和列的角色和类别,而使用模型中的行和列。默认值为false

访问功能:

bool useModelCategories() const
void setUseModelCategories(bool enable)

通知信号:

void useModelCategoriesChanged(bool enable)

valueRole : QString

该属性用于保存映射的值角色。

访问功能:

QString valueRole() const
void setValueRole(const QString &role)

通知信号:

void valueRoleChanged(const QString &role)

valueRolePattern : QRegularExpression

该属性表示是否在将值角色映射的值用作条形图值之前对其进行搜索和替换。

该属性指定正则表达式,用于查找要替换的映射值部分,valueRoleReplace 属性包含替换字符串。

访问功能:

QRegularExpression valueRolePattern() const
void setValueRolePattern(const QRegularExpression &pattern)

Notifier 信号:

void valueRolePatternChanged(const QRegularExpression &pattern)

另请参见 valueRolevalueRoleReplace

valueRoleReplace : QString

该属性包含与valueRolePattern 一起使用的替换内容。

默认为空字符串。有关使用正则表达式进行搜索和替换的工作原理,请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。

访问函数:

QString valueRoleReplace() const
void setValueRoleReplace(const QString &replace)

Notifier 信号:

void valueRoleReplaceChanged(const QString &replace)

另请参阅 valueRolevalueRolePattern

成员函数文档

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QObject *parent = nullptr)

构造带有可选parent 的 QItemModelBarDataProxy。

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr)

itemModel 和一个可选的parent 构造 QItemModelBarDataProxy。该代理不拥有itemModel 的所有权,因为项目模型通常由其他控件拥有。

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &valueRole, QObject *parent = nullptr)

itemModel 和一个可选的parent 构造 QItemModelBarDataProxy。该代理不拥有itemModel 的所有权,因为项目模型通常由其他控件拥有。值角色被设置为valueRole 。该构造函数的目的是与已按行和列正确排序数据的模型一起使用,因此它也将useModelCategories 属性设置为 true。

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, QObject *parent = nullptr)

itemModel 和一个可选的parent 构造 QItemModelBarDataProxy。该代理不拥有itemModel 的所有权,因为项目模型通常由其他控件拥有。角色映射由rowRolecolumnRolevalueRole 设置。

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, QObject *parent = nullptr)

itemModel 和一个可选的parent 构造 QItemModelBarDataProxy。该代理不拥有itemModel 的所有权,因为项目模型通常由其他控件拥有。角色映射由rowRole,columnRole,valueRolerotationRole 设置。

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)

itemModel 和一个可选的parent 构造 QItemModelBarDataProxy。该代理不拥有itemModel 的所有权,因为项目模型通常由其他控件拥有。角色映射通过rowRolecolumnRolevalueRole 设置。行和列类别通过rowCategoriescolumnCategories 设置。此构造函数还将autoRowCategoriesautoColumnCategories 设置为 false。

[explicit] QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)

itemModel 和一个可选的parent 构造 QItemModelBarDataProxy。该代理不拥有itemModel 的所有权,因为项目模型通常由其他控件拥有。角色映射通过rowRole,columnRole,valueRolerotationRole 设置。行和列类别通过rowCategoriescolumnCategories 设置。此构造函数还将autoRowCategoriesautoColumnCategories 设置为 false。

[override virtual noexcept] QItemModelBarDataProxy::~QItemModelBarDataProxy()

销毁QItemModelBarDataProxy

[invokable] qsizetype QItemModelBarDataProxy::columnCategoryIndex(const QString &category)

返回列类别列表中指定category 的索引。如果未找到类别,则返回-1。

注: 如果使用了自动生成列类别的功能,则在第一次解析模型中的数据之前,此方法不会返回有效的索引。

注: 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE

void QItemModelBarDataProxy::remap(const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories)

rowRole,columnRole,valueRole,rotationRole,rowCategoriescolumnCategories 更改为映射。

[invokable] qsizetype QItemModelBarDataProxy::rowCategoryIndex(const QString &category)

返回行类别列表中指定category 的索引。如果行类别列表为空,则返回-1。

注: 如果正在使用自动行类别生成功能,则在模型中的数据第一次解析之前,此方法不会返回有效索引。

注: 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE

void QItemModelBarDataProxy::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.