Back to Qt.io
Contact Us Blog Download Qt

Q3DBars Class

Q3DBars 类提供了渲染 3D 柱形图的方法。更多

Header： #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)

详细说明

通过该类，开发人员可以渲染三维条形图，并通过自由旋转场景查看条形图。旋转可通过按住鼠标右键并移动鼠标来完成。缩放通过鼠标滚轮完成。选择（如果启用）通过鼠标左键完成。单击鼠标滚轮可将场景重置为默认摄像机视图。在触摸设备中，旋转通过点击移动来完成，选择通过点击和按住来完成，缩放通过捏来完成。

如果没有将坐标轴明确设置为 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 x 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)

Notifier 信号：

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* const

该属性包含所选系列或空值。

如果 selectionMode 设置了SelectionMultiSeries 标志，此属性将保存所选条形图的系列。

访问功能：

QBar3DSeries *selectedSeries() const

通知信号：

void selectedSeriesChanged(QBar3DSeries *series)

valueAxis : QValue3DAxis*

将活动值轴（Y 轴）设置为axis 。隐式调用addAxis() 将axis 的所有权转移到该图表。

如果axis 为空，则会创建一个没有标签和自动调整范围的临时默认坐标轴。如果将另一个轴明确设置为相同方向，则会销毁该临时轴。

访问功能：

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

通知信号：

void valueAxisChanged(QValue3DAxis *axis)

另请参见 addAxis() 和releaseAxis()。

成员函数文档

[explicit] Q3DBars::Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)

构建新的三维条形图，可选parent 窗口和表面format 。

[virtual noexcept] Q3DBars::~Q3DBars()

销毁 3D 柱形图。

void Q3DBars::addAxis(QAbstract3DAxis *axis)

将axis 添加到图表中。通过 addAxis 添加的坐标轴尚未投入使用，addAxis 只是用来将axis 的所有权赋予图形。axis 不得为空或添加到其他图形中。

另请参阅 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 减一。

另请参阅 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 为空，则会创建一个没有标签的临时默认坐标轴。如果另一个轴被显式设置为相同方向，则该临时轴将被销毁。

注： 属性columnAxis 的设置函数。

另请参见 columnAxis()、addAxis() 和releaseAxis()。

void Q3DBars::setPrimarySeries(QBar3DSeries *series)

将series 设置为图表的主系列。如果坐标轴没有显式设置标签，则主系列将决定行坐标轴和列坐标轴的标签。

如果指定的序列尚未添加到图形中，将其设置为主序列也会将其隐式添加到图形中。

如果从图表中删除了主系列，该属性将重置为默认值。

如果series 为空，该属性将重置为默认值。默认为第一个添加的序列，如果没有序列添加到图表中，则默认为零。

注： 属性primarySeries 的设置函数。

另请参阅 primarySeries() 。

void Q3DBars::setRowAxis(QCategory3DAxis *axis)

将活动行的坐标轴设置为axis 。隐式调用addAxis() 将坐标轴的所有权转移到此图形。

如果axis 为空，则会创建一个没有标签的临时默认坐标轴。如果将另一个轴明确设置为相同方向，则会销毁该临时轴。

注： 属性rowAxis 的设置函数。

另请参见 rowAxis()、addAxis() 和releaseAxis()。

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