Back to Qt.io
Contact Us Blog Download Qt

Q3DSurfaceWidgetItem Class

Q3DSurfaceWidgetItem 类提供了渲染三维曲面图的方法。更多

Header： #include <Q3DSurfaceWidgetItem>
CMake： find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake： QT += graphswidgets
继承： Q3DGraphsWidgetItem

属性

公共功能

Q3DSurfaceWidgetItem(QObject *parent = nullptr)
virtual ~Q3DSurfaceWidgetItem() override
void addAxis(QValue3DAxis *axis)
void addSeries(QSurface3DSeries *series)
QList<QValue3DAxis *> axes() const
QValue3DAxis *axisX() const
QValue3DAxis *axisY() const
QValue3DAxis *axisZ() const
bool flipHorizontalGrid() const
void releaseAxis(QValue3DAxis *axis)
void removeSeries(QSurface3DSeries *series)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const
void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

信号

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void flipHorizontalGridChanged(bool flip)
void selectedSeriesChanged(QSurface3DSeries *series)

详细说明

通过该类，开发人员可以渲染三维曲面图，并通过自由旋转场景来查看它们。曲面的可视化属性（如绘制模式和阴影）可通过QSurface3DSeries 控制。

Q3DSurfaceWidgetItem 支持选择功能，在用户点击鼠标左键（使用默认输入处理程序时）或通过QSurface3DSeries 选择的数据点上显示一个高亮球。选择指针附带一个标签，默认情况下显示数据点的值和坐标。

坐标轴上显示的数值范围和标签格式可通过QValue3DAxis 控制。

要旋转图表，请按住鼠标右键并移动鼠标。缩放则使用鼠标滚轮。这两种操作都假定使用的是默认输入处理程序。

如果没有为 Q3DSurfaceWidgetItem 明确设置坐标轴，则会创建没有标签的临时默认坐标轴。这些默认坐标轴可通过坐标轴访问器修改，但一旦为方向明确设置了任何坐标轴，该方向的默认坐标轴就会被销毁。

如何构建最小的 Q3DSurfaceWidgetItem 图形

首先，构建 Q3DSurfaceWidgetItem。由于我们在本例中将图形作为顶层窗口运行，因此需要清除默认设置的Qt::FramelessWindowHint 标志：

QQuickWidget quickWidget;
Q3DSurfaceWidgetItem surface;
surface.setWidget(&quickWidget);
surface.widget()->setMinimumSize(QSize(256, 256));

现在，Q3DSurfaceWidgetItem 已准备好接收要渲染的数据。创建数据元素以接收数值：

注意： 在新的代理-系列关系中，数据是按系列保存的。因此，要使代理能够添加、删除或编辑数据，前提是先创建一个系列。

QSurfaceDataArray data;
QSurfaceDataRow dataRow1;
QSurfaceDataRow dataRow2;

首先将数据输入行元素，然后将其指针添加到数据元素：

dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f);
dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f);
data << dataRow1 << dataRow2;

创建一个新系列并为其设置数据：

QSurface3DSeries series;
series.dataProxy()->resetArray(data);
surface.addSeries(&series);

最后需要设置其可见性：

surface.widget()->show();

创建和显示此图表所需的完整代码如下：

#include <QtGraphs>
#include <QtGraphsWidgets/q3dsurfacewidgetitem.h>
#include <QtWidgets/qapplication.h>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QQuickWidget quickWidget;
    Q3DSurfaceWidgetItem surface;
    surface.setWidget(&quickWidget);
    surface.widget()->setMinimumSize(QSize(256, 256));
    QSurfaceDataArray data;
    QSurfaceDataRow dataRow1;
    QSurfaceDataRow dataRow2;

    dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f);
    dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f);
    data << dataRow1 << dataRow2;

    QSurface3DSeries series;
    series.dataProxy()->resetArray(data);
    surface.addSeries(&series);
    surface.widget()->show();

    return app.exec();
}

这就是这几行代码产生的结果：

场景可以旋转、缩放，还可以选择表面点查看其位置，但在这个最小代码示例中不包括其他交互。您可以通过熟悉所提供的示例（如曲面图库）了解更多信息。

另请参阅 Q3DBarsWidgetItem 、Q3DScatterWidgetItem 和Qt Graphs C++ 3D 类。

属性文档

axisX : QValue3DAxis*

该属性用于保存活动 x 轴。

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

如果axis 为空，则会创建一个没有标签和自动调整范围的临时默认坐标轴。

如果将另一个轴明确设置为相同方向，则会销毁该临时轴。

访问功能：

QValue3DAxis *axisX() const
void setAxisX(QValue3DAxis *axis)

通知信号：

void axisXChanged(QValue3DAxis *axis)

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

axisY : QValue3DAxis*

该属性用于保存活动 Y 轴。

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

如果axis 为空，则会创建一个没有标签和自动调整范围的临时默认坐标轴。

如果将另一个轴明确设置为相同方向，则会销毁该临时轴。

访问功能：

QValue3DAxis *axisY() const
void setAxisY(QValue3DAxis *axis)

通知信号：

void axisYChanged(QValue3DAxis *axis)

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

axisZ : QValue3DAxis*

该属性用于保存活动 Z 轴。

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

如果axis 为空，则会创建一个没有标签和自动调整范围的临时默认轴。

如果将另一个轴明确设置为相同方向，则会销毁该临时轴。

访问功能：

QValue3DAxis *axisZ() const
void setAxisZ(QValue3DAxis *axis)

通知信号：

void axisZChanged(QValue3DAxis *axis)

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

flipHorizontalGrid : bool

此属性表示水平轴网格是否显示在图形顶部而不是底部。

在某些使用情况下，水平轴网格大部分被表面覆盖，因此在图形顶部而不是底部显示水平轴网格可能更有用。一个典型的使用案例就是使用正投影法以自上而下的视角显示二维频谱图。

如果false ，横轴网格和标签将绘制在图表的水平背景上。如果为true ，则横轴网格和标签绘制在图形与水平背景相反的一侧。默认为false 。

访问功能：

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Notifier 信号：

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries* const

此属性表示所选系列或空。

如果设置了 selectionMode（选择模式）MultiSeries ，则此属性将保存拥有所选点的系列。

访问功能：

QSurface3DSeries *selectedSeries() const

Notifier 信号：

void selectedSeriesChanged(QSurface3DSeries *series)

成员函数 文档

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

用可选的parent 构建新的三维曲面图。

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

销毁 3D 表面图形。

void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)

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

另请参阅 releaseAxis()、setAxisX()、setAxisY() 和setAxisZ()。

void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)

将series 添加到图表中。图形可以包含多个序列，但只有一组坐标轴。如果新添加的序列已指定了一个选中项，则该选中项将突出显示，并且任何现有选中项都将被清除。只有一个添加的序列可以有一个活动选区。

另请参见 Q3DGraphsWidgetItem::hasSeries()。

QList<QValue3DAxis *> Q3DSurfaceWidgetItem::axes() const

返回所有已添加轴的列表。

另请参见 addAxis()。

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

如果axis 已添加到此图形中，则将其所有权释放给调用者。如果被释放的axis 正在使用中，将创建一个新的默认坐标轴并将其设置为活动状态。

如果默认轴被释放并在稍后添加回来，它的行为与其他轴一样。

另请参见 addAxis()、setAxisX()、setAxisY() 和setAxisZ()。

void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

从图表中删除series 。

另请参见 Q3DGraphsWidgetItem::hasSeries().

QList<QSurface3DSeries *> Q3DSurfaceWidgetItem::seriesList() const

返回添加到此图表的系列列表。

另请参阅 Q3DGraphsWidgetItem::hasSeries()。

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