本页内容

QBar3DSeries Class

QBar3DSeries 类表示三维条形图中的数据系列。更多内容...

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

属性

公共函数

QBar3DSeries(QObject *parent = nullptr)
QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent = nullptr)
virtual ~QBar3DSeries() override
void clearArray()
void clearRow(qsizetype rowIndex)
QCategory3DAxis *columnAxis() const
QStringList columnLabels() const
QStringList customColumnLabels() const
QStringList customRowLabels() const
const QBarDataArray &dataArray() const &
QBarDataArray dataArray() &&
QBarDataProxy *dataProxy() const
bool isValueColoringEnabled() const
float meshAngle() const
void resetColumnAxis()
void resetRowAxis()
void resetValueAxis()
QCategory3DAxis *rowAxis() const
QList<QColor> rowColors() const
QStringList rowLabels() const
QPoint selectedBar() const
void setColumnAxis(QCategory3DAxis *axis)
void setColumnLabels(const QStringList &labels)
void setCustomColumnLabels(const QStringList &labels)
void setCustomRowLabels(const QStringList &labels)
void setDataArray(const QBarDataArray &newDataArray)
void setDataProxy(QBarDataProxy *proxy)
void setMeshAngle(float angle)
void setRowAxis(QCategory3DAxis *axis)
void setRowColors(const QList<QColor> &colors)
void setRowLabels(const QStringList &labels)
void setSelectedBar(QPoint position)
void setValueAxis(QValue3DAxis *axis)
void setValueColoringEnabled(bool enabled)
QValue3DAxis *valueAxis() const

信号

void columnAxisChanged(QCategory3DAxis *axis)
void columnLabelsChanged()
void customColumnLabelsChanged(const QStringList &newCustomColumnLabels)
void customRowLabelsChanged(const QStringList &newCustomRowLabels)
void dataArrayChanged(const QBarDataArray &array)
void dataProxyChanged(QBarDataProxy *proxy)
void meshAngleChanged(float angle)
void rowAxisChanged(QCategory3DAxis *axis)
void rowColorsChanged(const QList<QColor> &rowcolors)
void rowLabelsChanged()
void selectedBarChanged(QPoint position)
void valueAxisChanged(QValue3DAxis *axis)
void valueColoringEnabledChanged(bool enabled)

静态公共成员

详细说明

该类管理系列特有的视觉元素,以及系列数据(通过数据代理)。

关于代理与序列的关系,有几个关键点必须强调。 在此背景下,数据存储在系列中,用户可以通过系列访问数据集。该系列由一个代理对象控制或表示。因此,代理可用于管理数据上的各种操作并更新实际数据集。但是,要编辑数据集,必须创建一个与该代理关联的系列。

如果未为序列显式设置数据代理,则序列会创建一个默认代理。设置另一个代理将销毁现有代理以及添加到该序列中的所有数据。

QBar3DSeries 支持以下用于 `QAbstract3DSeries::setItemLabelFormat()` 的格式标签:

@rowTitle来自行轴的标题
@colTitle来自列轴的标题
@valueTitle值轴的标题
@rowIdx可见行索引。根据图表区域设置进行本地化。
@colIdx可见列索引。使用图的区域设置进行本地化。
@rowLabel来自行轴的标签
@colLabel来自列轴的标签
@valueLabel使用图表所附值轴的格式进行格式化的项目值。有关更多信息,请参阅QValue3DAxis::labelFormat 。
@seriesName数据系列的名称
%<格式规范>以指定格式显示的项目值。格式化规则与QValue3DAxis::labelFormat 相同。

例如:

proxy->setItemLabelFormat(QStringLiteral("@valueTitle for (@rowLabel, @colLabel): %.1f"));

另请参阅 Qt Graphs 中的“3D 数据处理”以及Q3DGraphsWidgetItem::locale 。

属性文档

[since 6.11] columnAxis : QCategory3DAxis*

为该数据系列添加一个额外的列坐标轴

注意:该 附加坐标轴不会调整图表的布局,但可提供一组额外的标签和坐标轴网格。

此枚举在 Qt 6.11 中引入。

访问函数:

QCategory3DAxis *columnAxis() const
void setColumnAxis(QCategory3DAxis *axis)
void resetColumnAxis()

通知器信号:

void columnAxisChanged(QCategory3DAxis *axis)

columnLabels : QStringList

该属性存储数组的可选列标签。

该数组中的索引与行中的列索引相对应。如果列表长度小于最长行,则并非所有列都会获得标签。

访问函数:

QStringList columnLabels() const
void setColumnLabels(const QStringList &labels)

通知信号:

void columnLabelsChanged()

[since 6.11] customColumnLabels : QStringList

该属性用于存储数组的可选自定义列标签。

这些标签将覆盖代理生成的任何标签。该数组中的索引与行中的列索引相对应。如果列表的长度小于最长行,则并非所有列都会获得标签。

该枚举在 Qt 6.11 中引入。

访问函数:

QStringList customColumnLabels() const
void setCustomColumnLabels(const QStringList &labels)

通知器信号:

void customColumnLabelsChanged(const QStringList &newCustomColumnLabels)

[since 6.11] customRowLabels : QStringList

该属性用于存储数组的可选自定义行标签。

这些标签将覆盖代理生成的任何标签。该数组中的索引与数据数组中的行索引相对应。如果列表长度小于行数,则并非所有行都会获得标签。

此枚举类型在 Qt 6.11 中引入。

访问函数:

QStringList customRowLabels() const
void setCustomRowLabels(const QStringList &labels)

通知器信号:

void customRowLabelsChanged(const QStringList &newCustomRowLabels)

dataArray : QBarDataArray

该序列的数据数组。

保存数据数组的引用。

当数据数组被设置时,会触发 dataArrayChanged 信号,除非newDataArray 与上一次完全相同。

注意: 在对 dataArray 进行任何操作之前, 必须先 为相关代理创建一个系列。

访问函数:

const QBarDataArray &dataArray() const &
QBarDataArray dataArray() &&
void setDataArray(const QBarDataArray &newDataArray)

通知信号:

void dataArrayChanged(const QBarDataArray &array)

另请参阅 clearRow(qsizetype rowIndex) 和clearArray()。

dataProxy : QBarDataProxy*

该属性保存活动数据代理。

该系列会接管其上设置的任何代理,并在添加新代理时删除先前设置的代理。代理不能为空,也不能设置为另一个系列。

访问函数:

QBarDataProxy *dataProxy() const
void setDataProxy(QBarDataProxy *proxy)

通知信号:

void dataProxyChanged(QBarDataProxy *proxy)

meshAngle : float

该属性存储序列的旋转角度(单位为度)。

设置此属性等同于以下调用:

setMeshRotation(QQuaternion::fromAxisAndAngle(0.0f, 1.0f, 0.0f, angle))

注意: 读取此属性时 ,系统会根据QAbstract3DSeries::meshRotation 的值采用浮点精度进行计算,并始终返回0至360度之间的值。

访问函数:

float meshAngle() const
void setMeshAngle(float angle)

通知信号:

void meshAngleChanged(float angle)

另请参阅 QAbstract3DSeries::meshRotation 。

[since 6.11] rowAxis : QCategory3DAxis*

为该数据系列添加一个额外的行轴

注意:该 附加坐标轴不会调整图表的拟合效果,但可提供额外的一组标签和坐标轴网格。

此枚举类型在 Qt 6.11 中引入。

访问函数:

QCategory3DAxis *rowAxis() const
void setRowAxis(QCategory3DAxis *axis)
void resetRowAxis()

通知器信号:

void rowAxisChanged(QCategory3DAxis *axis)

rowColors : QList<QColor>

该属性保存了该系列中行颜色的列表。

该属性可用于将系列的行设置为不同的颜色。要使用此属性,必须将QGraphsTheme::ColorStyle 设置为QGraphsTheme::ColorStyle::Uniform 。

访问函数:

QList<QColor> rowColors() const
void setRowColors(const QList<QColor> &colors)

通知信号:

void rowColorsChanged(const QList<QColor> &rowcolors)

另请参阅 QGraphsTheme::ColorStyle::Uniform 。

rowLabels : QStringList

该属性存储数组的可选行标签。

该数组中的索引与数据数组中的行索引相对应。如果列表的长度小于行数,则并非所有行都会获得标签。

访问函数:

QStringList rowLabels() const
void setRowLabels(const QStringList &labels)

通知信号:

void rowLabelsChanged()

selectedBar : QPoint

该属性保存所选系列中的条形。

访问函数:

QPoint selectedBar() const
void setSelectedBar(QPoint position)

通知信号:

void selectedBarChanged(QPoint position)

[since 6.11] valueAxis : QValue3DAxis*

为该数据系列保留一个额外的数值轴。如果指定了该轴,则该数据系列将根据该轴的最小值和最大值进行适配。

该枚举类型在 Qt 6.11 中引入。

访问函数:

QValue3DAxis *valueAxis() const
void setValueAxis(QValue3DAxis *axis)
void resetValueAxis()

通知器信号:

void valueAxisChanged(QValue3DAxis *axis)

[since 6.9] valueColoringEnabled : bool

使用给定的值,根据范围渐变为整个柱状图着色

此属性可用于根据每个条形的数值和给定的范围渐变,分别对其进行着色。要使用此属性,必须将QGraphsTheme::ColorStyle 设置为QGraphsTheme::ColorStyle::RangeGradient 。

该枚举类型在 Qt 6.9 中引入。

访问函数:

bool isValueColoringEnabled() const
void setValueColoringEnabled(bool enabled)

通知器信号:

void valueColoringEnabledChanged(bool enabled)

另请参阅 QGraphsTheme::ColorStyle::RangeGradient 。

成员函数文档

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

使用父对象parent 构建一个条形图3D系列。

[explicit] QBar3DSeries::QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent = nullptr)

使用数据代理dataProxy 和父对象parent 构建一个条形图3D系列。

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

删除一个条形3D数据系列。

void QBar3DSeries::clearArray()

清空现有数组。

void QBar3DSeries::clearRow(qsizetype rowIndex)

根据给定的rowIndex ,清除数组中现有的行。

[static] QPoint QBar3DSeries::invalidSelectionPosition()

返回一个无效的选择位置。将该位置设置为selectedBar 属性,以清除该系列中的选择。

另请参阅 Q3DGraphsWidgetItem::clearSelection()。

void QBar3DSeries::setSelectedBar(QPoint position)

选择位于position 位置的柱形,该位置由系列数据数组中的行和列指定。

每次只能选择一个柱形图。

要清除此系列中的选中项,需将invalidSelectionPosition()设置为position 。

如果将该系列添加到图表中,图表可根据用户交互或在选择失效时调整选择。选择另一个已添加系列中的条形图也会清除当前的选择。

从该系列中删除行或在选定柱形所在行的前面插入行,将调整选定范围,以便保持对同一柱形的选定状态。

注意: 这是属性selectedBar 的设置 函数。

另请参阅 selectedBar() 和Q3DGraphsWidgetItem::clearSelection()。

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