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 |
- 所有成员列表（包括继承的成员）
- QItemModelBarDataProxy 属于Qt Graphs 的3D C++类库。
公共类型
| 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::First | 0 | 该值取自项目模型中与每行/列组合相匹配的第一个项目。 |
QItemModelBarDataProxy::MultiMatchBehavior::Last | 1 | 该值取自项目模型中与每行/列组合匹配的最后一项。 |
QItemModelBarDataProxy::MultiMatchBehavior::Average | 2 | 将匹配每行/列组合的所有项目的值求平均，并将平均值用作条形图的值。 |
QItemModelBarDataProxy::MultiMatchBehavior::Cumulative | 3 | 将匹配每个行/列组合的所有项目的值相加，并将总和用作条形图的值。 |
属性文档
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
该属性用于指定映射中的列角色。
访问函数：
| 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
该属性存储与columnRolePattern 配合使用的替换内容。
默认值为空字符串。有关使用正则表达式进行搜索和替换的工作原理的更多信息，请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数的文档。
访问函数：
| QString | columnRoleReplace() const |
| void | setColumnRoleReplace(const QString &replace) |
通知信号：
| void | columnRoleReplaceChanged(const QString &replace) |
另请参阅 columnRole 和columnRolePattern 。
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) |
通知信号：
| void | rotationRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 rotationRole 和rotationRoleReplace 。
rotationRoleReplace : QString
该属性用于存储与rotationRolePattern 配合使用的替换内容。
默认值为空字符串。有关使用正则表达式进行搜索和替换的工作原理的更多信息，请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。
访问函数：
| QString | rotationRoleReplace() const |
| void | setRotationRoleReplace(const QString &replace) |
通知信号：
| void | rotationRoleReplaceChanged(const QString &replace) |
另请参阅 rotationRole 和rotationRolePattern 。
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) |
通知信号：
| void | rowRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 rowRole 和rowRoleReplace 。
rowRoleReplace : QString
该属性存储与rowRolePattern 配合使用的替换内容。
默认值为空字符串。有关使用正则表达式进行搜索和替换的工作原理的更多信息，请参阅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) |
valueRole : QString
该属性在映射中起“角色”作用。
访问函数：
| QString | valueRole() const |
| void | setValueRole(const QString &role) |
通知器信号：
| void | valueRoleChanged(const QString &role) |
valueRolePattern : QRegularExpression
该属性用于指定在将“value”角色映射的值用作条形图值之前，是否对其进行搜索和替换操作。
该属性指定用于查找映射值中待替换部分的正则表达式，而valueRoleReplace 属性则包含替换字符串。
访问函数：
| QRegularExpression | valueRolePattern() const |
| void | setValueRolePattern(const QRegularExpression &pattern) |
通知信号：
| void | valueRolePatternChanged(const QRegularExpression &pattern) |
另请参阅 valueRole 和valueRoleReplace 。
valueRoleReplace : QString
该属性存储将与valueRolePattern 配合使用的替换内容。
默认值为空字符串。有关使用正则表达式进行搜索和替换的更多信息，请参阅QString::replace(constQRegularExpression &rx, constQString &after) 函数文档。
访问函数：
| QString | valueRoleReplace() const |
| void | setValueRoleReplace(const QString &replace) |
通知信号：
| void | valueRoleReplaceChanged(const QString &replace) |
另请参阅 valueRole 和valueRolePattern 。
成员函数文档
[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 的所有权，因为通常项模型由其他控件拥有。角色映射通过rowRole 、columnRole 和valueRole 进行设置。
[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 、valueRole 和rotationRole 进行设置。
[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 的所有权，因为通常项模型由其他控件拥有。角色映射通过rowRole 、columnRole 和valueRole 进行设置。行和列类别分别通过rowCategories 和columnCategories 进行设置。此构造函数还会将autoRowCategories 和autoColumnCategories 设置为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 、valueRole 和rotationRole 进行设置。行和列类别通过rowCategories 和columnCategories 进行设置。此构造函数还将autoRowCategories 和autoColumnCategories 设置为false。
[override virtual noexcept] 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 、rowCategories 和columnCategories 进行了修改。
[invokable] qsizetype QItemModelBarDataProxy::rowCategoryIndex(const QString &category)
返回指定category 在行类别列表中的索引。如果行类别列表为空，则返回-1。
注意：如果 启用了自动生成行类别功能，在模型中的数据首次解析之前，此方法不会返回有效的索引。
注意： 可以通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
void QItemModelBarDataProxy::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.
