Q3DBars Class
Q3DBars 类提供了用于渲染 3D 条形图的方法。更多内容...
| 头文件： | #include <Q3DBars> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS DataVisualization) target_link_libraries(mytarget PRIVATE Qt6::DataVisualization) |
| qmake: | QT += datavisualization |
| 自： | QtDataVisualization 1.0 |
| 继承自： | QAbstract3DGraph |
| 状态： | 已弃用 |
该类已弃用。我们强烈建议不要在新代码中使用它。
属性
|
|
公共函数
| Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr) | |
| virtual | ~Q3DBars() |
| void | addAxis(QAbstract3DAxis *axis) |
| void | addSeries(QBar3DSeries *series) |
| QList<QAbstract3DAxis *> | axes() const |
| QSizeF | barSeriesMargin() const |
| QSizeF | barSpacing() const |
| float | barThickness() const |
| QCategory3DAxis * | columnAxis() const |
| float | floorLevel() const |
| void | insertSeries(int index, QBar3DSeries *series) |
| bool | isBarSpacingRelative() const |
| bool | isMultiSeriesUniform() const |
| QBar3DSeries * | primarySeries() const |
| void | releaseAxis(QAbstract3DAxis *axis) |
| void | removeSeries(QBar3DSeries *series) |
| QCategory3DAxis * | rowAxis() const |
| QBar3DSeries * | selectedSeries() const |
| QList<QBar3DSeries *> | seriesList() const |
| void | setBarSeriesMargin(const QSizeF &margin) |
| void | setBarSpacing(const QSizeF &spacing) |
| void | setBarSpacingRelative(bool relative) |
| void | setBarThickness(float thicknessRatio) |
| void | setColumnAxis(QCategory3DAxis *axis) |
| void | setFloorLevel(float level) |
| void | setMultiSeriesUniform(bool uniform) |
| void | setPrimarySeries(QBar3DSeries *series) |
| void | setRowAxis(QCategory3DAxis *axis) |
| void | setValueAxis(QValue3DAxis *axis) |
| QValue3DAxis * | valueAxis() const |
信号
| void | barSeriesMarginChanged(const QSizeF &margin) |
| void | barSpacingChanged(const QSizeF &spacing) |
| void | barSpacingRelativeChanged(bool relative) |
| void | barThicknessChanged(float thicknessRatio) |
| void | columnAxisChanged(QCategory3DAxis *axis) |
| void | floorLevelChanged(float level) |
| void | multiSeriesUniformChanged(bool uniform) |
| void | primarySeriesChanged(QBar3DSeries *series) |
| void | rowAxisChanged(QCategory3DAxis *axis) |
| void | selectedSeriesChanged(QBar3DSeries *series) |
| void | valueAxisChanged(QValue3DAxis *axis) |
详细说明
该类允许开发人员渲染 3D 条形图，并通过自由旋转场景来查看这些图表。旋转操作通过按住鼠标右键并移动鼠标来实现。缩放操作通过鼠标滚轮完成。如果启用了选择功能，则通过鼠标左键进行选择。点击鼠标滚轮可将场景重置为默认摄像机视图。 在触摸设备上，旋转通过“轻点并拖动”实现，选择通过“轻点并长按”实现，缩放通过“双指捏合”实现。
如果未向 Q3DBars 显式设置坐标轴，则会创建无标签的临时默认坐标轴。这些默认坐标轴可通过坐标轴访问器进行修改，但一旦为某个方向显式设置了坐标轴，该方向的默认坐标轴即被销毁。
Q3DBars 支持同时显示多个系列。各系列的行数和列数不必相同。行和列标签默认取自第一个添加的系列，除非在行轴和列轴上显式定义。
如何构建一个最简的 Q3DBars 图表
首先，创建一个 Q3DBars 实例。由于本例中图表作为顶级窗口运行，我们需要清除默认设置的 `Qt::FramelessWindowHint ` 标志：
Q3DBars bars;
bars.setFlags(bars.flags() ^ Qt::FramelessWindowHint);创建 Q3DBars 实例后，您可以通过修改行轴和列轴的范围来设置数据窗口。这并非强制要求，因为数据窗口默认会显示系列中的所有数据。如果数据量较大，通常建议仅显示其中的一部分。 在本示例中，我们将数据窗口设置为仅显示前五行和前五列：
bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);现在，Q3DBars 已准备好接收待渲染的数据。创建一个包含一行 5 个值的系列：
QBar3DSeries *series = new QBar3DSeries;
QBarDataRow *data = new QBarDataRow;
*data << 1.0f << 3.0f << 7.5f << 5.0f << 2.2f;
series->dataProxy()->addRow(data);
bars.addSeries(series);注意：我们虽然 将数据窗口设置为 5×5，但仅添加了一行数据。这没有问题，其余行将保持空白。
最后，您需要将其设为可见：
bars.show();创建并显示此图表所需的完整代码如下：
#include <QtDataVisualization>
int main(int argc, char **argv)
{
qputenv("QSG_RHI_BACKEND", "opengl");
QGuiApplication app(argc, argv);
Q3DBars bars;
bars.setFlags(bars.flags() ^ Qt::FramelessWindowHint);
bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);
QBar3DSeries *series = new QBar3DSeries;
QBarDataRow *data = new QBarDataRow;
*data << 1.0f << 3.0f << 7.5f << 5.0f << 2.2f;
series->dataProxy()->addRow(data);
bars.addSeries(series);
bars.show();
return app.exec();
}而这几行代码生成的效果如下：
该场景支持旋转、缩放，并可选中条形查看其数值，但此精简代码示例中未包含其他交互功能。您可以通过熟悉提供的示例（如“条形图”）来深入了解。
另请参阅 Q3DScatter 、Q3DSurface 以及 Qt Data Visualization C++ Classes。
属性文档
[since 6.3] barSeriesMargin : QSizeF
X 和 Z 维度中各系列列之间的间距。合理的取值范围为 [0,1)。
默认预设值为(0.0, 0.0) 。此属性可使不同系列的柱形图并排显示，同时在各列之间保留间距。
该枚举类型在 Qt 6.3 中引入。
访问函数：
| QSizeF | barSeriesMargin() const |
| void | setBarSeriesMargin(const QSizeF &margin) |
通知信号：
| void | barSeriesMarginChanged(const QSizeF &margin) |
另请参阅 barSpacing 。
barSpacing : QSizeF
X 和 Z 方向上的条间距。
默认预设值为(1.0, 1.0) 。间距受barSpacingRelative 属性的影响。
访问函数：
| QSizeF | barSpacing() const |
| void | setBarSpacing(const QSizeF &spacing) |
通知信号：
| void | barSpacingChanged(const QSizeF &spacing) |
另请参阅 barSpacingRelative 、multiSeriesUniform 和barSeriesMargin 。
barSpacingRelative : bool
无论间距是绝对的还是相对于条形厚度而言的，此属性均有效。
如果该属性为true ，则0.0 的值表示条形并排排列，1.0 表示条形之间留有与单个条形厚度等宽的间距，以此类推。默认值为true 。
访问函数：
| bool | isBarSpacingRelative() const |
| void | setBarSpacingRelative(bool relative) |
通知信号：
| void | barSpacingRelativeChanged(bool relative) |
barThickness : float
此属性控制条形在X轴和Z轴方向上的厚度比例。
值1.0 表示条形件的宽度等于其深度，而0.5 则表示其深度是宽度的两倍。默认预设值为1.0 。
访问函数：
| float | barThickness() const |
| void | setBarThickness(float thicknessRatio) |
通知信号：
| void | barThicknessChanged(float thicknessRatio) |
columnAxis : QCategory3DAxis*
该属性保存与活动列关联的坐标轴。
访问函数：
| QCategory3DAxis * | columnAxis() const |
| void | setColumnAxis(QCategory3DAxis *axis) |
通知信号：
| void | columnAxisChanged(QCategory3DAxis *axis) |
floorLevel : float
该属性用于指定条形图在Y轴数据坐标系中的下限。
实际底线将受Y轴最小值和最大值的限制。默认值为零。
访问函数：
| float | floorLevel() const |
| void | setFloorLevel(float level) |
通知信号：
| void | floorLevelChanged(float level) |
multiSeriesUniform : bool
无论显示的是多个系列还是仅显示一个系列，此属性均决定条形是否应根据该单一系列的比例进行缩放。
如果设置为true ，则bar spacing 仅会正确应用于X轴。默认预设为false 。
访问函数：
| bool | isMultiSeriesUniform() const |
| void | setMultiSeriesUniform(bool uniform) |
通知信号：
| void | multiSeriesUniformChanged(bool uniform) |
primarySeries : QBar3DSeries*
该属性存储图的主序列。
访问函数：
| QBar3DSeries * | primarySeries() const |
| void | setPrimarySeries(QBar3DSeries *series) |
通知信号：
| void | primarySeriesChanged(QBar3DSeries *series) |
rowAxis : QCategory3DAxis*
该属性存储与当前活动行关联的坐标轴。
访问函数：
| QCategory3DAxis * | rowAxis() const |
| void | setRowAxis(QCategory3DAxis *axis) |
通知信号：
| void | rowAxisChanged(QCategory3DAxis *axis) |
[read-only] selectedSeries : QBar3DSeries*
该属性存储所选系列或一个空值。
如果 selectionMode 设置了SelectionMultiSeries 标志，则该属性将保存拥有所选柱状图的系列。
访问函数：
| QBar3DSeries * | selectedSeries() const |
通知器信号：
| void | selectedSeriesChanged(QBar3DSeries *series) |
valueAxis : QValue3DAxis*
将活动值轴（Y 轴）设置为 `axis`。隐式调用 `addAxis()` 将 `axis ` 的所有权转移至该图表。
如果 `axis ` 为 `null`，则会创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的方位，则该临时坐标轴将被销毁。
访问函数：
| QValue3DAxis * | valueAxis() const |
| void | setValueAxis(QValue3DAxis *axis) |
通知器信号：
| void | valueAxisChanged(QValue3DAxis *axis) |
另请参阅 addAxis() 和releaseAxis()。
成员函数文档
[explicit] Q3DBars::Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)
创建一个新的 3D 条形图，可选地设置窗口parent 和曲面format 。
[virtual noexcept] Q3DBars::~Q3DBars()
删除该3D柱状图。
void Q3DBars::addAxis(QAbstract3DAxis *axis)
将axis 添加到图中。通过addAxis添加的坐标轴尚未被用于实际使用，addAxis仅用于将axis 的所有权赋予该图。axis 不能为null，也不能已被添加到其他图中。
另请参阅 releaseAxis()、setValueAxis()、setRowAxis() 以及setColumnAxis()。
void Q3DBars::addSeries(QBar3DSeries *series)
将series 添加到图表中。一个图表可以包含多个系列，但只能有一组坐标轴，因此所有系列的行和列必须匹配，可视化数据才有意义。 如果图表中有多个可见系列，且未在坐标轴上显式设置标签，则只有主系列会在坐标轴上生成行或列标签。如果新添加的系列指定了选中条形，该条形将被高亮显示，且任何现有的选中状态都会被清除。仅有一个已添加的系列可以处于选中状态。
另请参阅 seriesList()、primarySeries 以及QAbstract3DGraph::hasSeries()。
QList<QAbstract3DAxis *> Q3DBars::axes() const
返回所有已添加坐标轴的列表。
另请参阅 addAxis()。
void Q3DBars::insertSeries(int index, QBar3DSeries *series)
将series 插入到序列列表中的index 位置。如果series 已添加到列表中，则将其移动到新的index 位置。
注意：当 将系列移动到位于其旧索引之后的新index 时 ，列表中的新位置是按照该系列仍位于旧索引的位置来计算的，因此最终索引实际上是index 减去1。
另请参阅 addSeries()、seriesList() 和QAbstract3DGraph::hasSeries()。
void Q3DBars::releaseAxis(QAbstract3DAxis *axis)
如果该axis 已被添加到此图中，则将其所有权交还给调用方。如果被释放的axis 正在被使用，则会创建一个新的默认轴并将其设为活动状态。
如果默认轴已被释放，随后又被重新添加，其行为将与其他轴相同。
另请参阅 addAxis()、setValueAxis()、setRowAxis() 以及setColumnAxis()。
void Q3DBars::removeSeries(QBar3DSeries *series)
从图中移除series 。
另请参阅 QAbstract3DGraph::hasSeries()。
QList<QBar3DSeries *> Q3DBars::seriesList() const
返回已添加到该图表的系列列表。
另请参阅 QAbstract3DGraph::hasSeries()。
void Q3DBars::setColumnAxis(QCategory3DAxis *axis)
将活动列的坐标轴设置为axis 。该方法会隐式调用addAxis()，将该坐标轴的所有权转移给此图。
如果axis 为 null，则会创建一个没有标签的临时默认坐标轴。如果显式地将另一个坐标轴设置为相同的方位，则该临时坐标轴将被销毁。
注意： 这是属性columnAxis 的设置 函数。
另请参阅 columnAxis()、addAxis() 和releaseAxis()。
void Q3DBars::setPrimarySeries(QBar3DSeries *series)
将series 设置为图表的主序列。当未在坐标轴上显式设置标签时，主序列将决定行轴和列轴的标签。
如果指定的数据列尚未添加到图表中，将其设置为主数据列也会将其隐式地添加到图表中。
如果主系列本身从图表中被移除，则此属性将重置为默认值。
如果series 为 null，则该属性将重置为默认值。默认值为第一个添加的系列；如果图表中未添加任何系列，则默认值为零。
注意： 属性 `primarySeries`的设置 函数。
另请参阅 primarySeries()。
void Q3DBars::setRowAxis(QCategory3DAxis *axis)
将活动行的坐标轴设置为axis 。该操作会隐式调用addAxis()，将该坐标轴的所有权转移给此图形。
如果 `axis ` 为 `null`，则会创建一个没有标签的临时默认坐标轴。如果显式将另一个坐标轴设置为相同的方位，则该临时坐标轴将被销毁。
注意： 这是属性rowAxis 的设置器 函数。
另请参阅 rowAxis()、addAxis() 和releaseAxis()。
© 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.
