Q3DScatterWidgetItem Class
Q3DScatterWidgetItem 类提供了用于渲染 3D 散点图的方法。更多内容...
| 头文件： | #include <Q3DScatterWidgetItem> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets) target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets) |
| qmake： | QT += graphswidgets |
| 继承自： | Q3DGraphsWidgetItem |
- 所有成员列表（包括继承的成员）
- Q3DScatterWidgetItem 属于Qt Graphs 小部件 C++ 类库。
属性
- axisX : QValue3DAxis*
- axisY : QValue3DAxis*
- axisZ : QValue3DAxis*
- selectedSeries : QScatter3DSeries*
公共函数
| Q3DScatterWidgetItem(QObject *parent = nullptr) | |
| virtual | ~Q3DScatterWidgetItem() override |
| void | addAxis(QValue3DAxis *axis) |
| void | addSeries(QScatter3DSeries *series) |
| QList<QValue3DAxis *> | axes() const |
| QValue3DAxis * | axisX() const |
| QValue3DAxis * | axisY() const |
| QValue3DAxis * | axisZ() const |
| void | releaseAxis(QValue3DAxis *axis) |
| void | removeSeries(QScatter3DSeries *series) |
| QScatter3DSeries * | selectedSeries() const |
| QList<QScatter3DSeries *> | seriesList() const |
公共插槽
| void | setAxisX(QValue3DAxis *axis) |
| void | setAxisY(QValue3DAxis *axis) |
| void | setAxisZ(QValue3DAxis *axis) |
信号
| void | axisXChanged(QValue3DAxis *axis) |
| void | axisYChanged(QValue3DAxis *axis) |
| void | axisZChanged(QValue3DAxis *axis) |
| void | selectedSeriesChanged(QScatter3DSeries *series) |
详细说明
该类允许开发者渲染 3D 散点图，并通过自由旋转场景来查看它们。旋转操作可通过按住鼠标右键并移动鼠标来实现，而缩放则通过鼠标滚轮完成。如果已启用，则使用鼠标左键进行选择。 点击鼠标滚轮可将场景重置为默认摄像机视图。在触控设备上，通过“轻点并拖动”实现旋转，通过“轻点并长按”实现选择，通过“双指缩放”实现缩放。
如果未向 Q3DScatterWidgetItem 显式设置坐标轴，则会创建无标签的临时默认坐标轴。这些默认坐标轴可通过坐标轴访问器进行修改，但一旦为某个方向显式设置了坐标轴，该方向的默认坐标轴即被销毁。
Q3DScatterWidgetItem 支持同时显示多个数据系列。
Q3DScatterWidgetItem 支持透明度。此功能允许您调整散点图中数据点的不透明度，使其呈现半透明、完全透明或不透明的效果。
如何构建一个最简化的 Q3DScatterWidgetItem 图表
首先，创建 Q3DScatterWidgetItem。由于本示例中图表作为顶级窗口运行，我们需要清除默认已设置的 `Qt::FramelessWindowHint ` 标志：
QQuickWidget quickWidget;
Q3DScatterWidgetItem scatter;
scatter.setWidget(&quickWidget);
scatter.widget()->setMinimumSize(QSize(256, 256));现在，Q3DScatterWidgetItem 已准备好接收待渲染的数据。添加一个包含 3 个QVector3D 项的系列：
注意：在 新的代理-系列关系中 ，数据存储在系列中。因此，为了使代理能够添加、删除或编辑数据，必须先创建一个系列。
QScatter3DSeries series;
QScatterDataArray data;
data << QScatterDataItem(0.5f, 0.5f, 0.5f) << QScatterDataItem(-0.3f, -0.5f, -0.4f)
<< QScatterDataItem(0.0f, -0.3f, 0.2f);
series.dataProxy()->addItems(data);
scatter.addSeries(&series);最后，您需要将其设为可见：
scatter.widget()->show();创建并显示此图表所需的完整代码如下：
#include <QtGraphs>
#include <QtGraphsWidgets/q3dscatterwidgetitem.h>
#include <QtWidgets/qapplication.h>
int main(int argc, char **argv)
{
QApplication app(argc, argv);
QQuickWidget quickWidget;
Q3DScatterWidgetItem scatter;
scatter.setWidget(&quickWidget);
scatter.widget()->setMinimumSize(QSize(256, 256));
QScatter3DSeries series;
QScatterDataArray data;
data << QScatterDataItem(0.5f, 0.5f, 0.5f) << QScatterDataItem(-0.3f, -0.5f, -0.4f)
<< QScatterDataItem(0.0f, -0.3f, 0.2f);
series.dataProxy()->addItems(data);
scatter.addSeries(&series);
scatter.widget()->show();
return app.exec();
}以下是这几行代码生成的效果：
该场景支持旋转、缩放，并可选中项目查看其位置，但此精简代码示例中未包含其他交互功能。您可以通过熟悉提供的示例（如“简单散点图”）来了解更多内容。
另请参阅 Q3DBarsWidgetItem 、Q3DSurfaceWidgetItem 以及Qt Graphs 中的 3D C++ 类。
属性文档
axisX : QValue3DAxis*
该属性用于指定当前活动的 x 轴。
将axis 设置为活动x轴。会隐式调用addAxis()，将该轴的所有权转移至此图形。
如果 `axis ` 为 `null`，则会创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的方向，则该临时坐标轴将被销毁。
访问函数：
| QValue3DAxis * | axisX() const |
| void | setAxisX(QValue3DAxis *axis) |
通知信号：
| void | axisXChanged(QValue3DAxis *axis) |
另请参阅 addAxis() 和releaseAxis()。
axisY : QValue3DAxis*
该属性用于指定当前活动的y轴。
将axis 设置为活动y轴。会隐式调用addAxis()，将该轴的所有权转移至此图形。
如果 `axis ` 为 `null`，则会创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的方位，则该临时坐标轴将被销毁。
访问函数：
| QValue3DAxis * | axisY() const |
| void | setAxisY(QValue3DAxis *axis) |
通知信号：
| void | axisYChanged(QValue3DAxis *axis) |
另请参阅 addAxis() 和releaseAxis()。
axisZ : QValue3DAxis*
该属性用于指定当前活动的 z 轴。
将axis 设置为活动Z轴。会隐式调用addAxis()，将该轴的所有权转移至此图形。
如果 `axis ` 为 `null`，则会创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式地将另一个坐标轴设置为相同的朝向，则该临时坐标轴将被销毁。
访问函数：
| QValue3DAxis * | axisZ() const |
| void | setAxisZ(QValue3DAxis *axis) |
通知信号：
| void | axisZChanged(QValue3DAxis *axis) |
另请参阅 addAxis() 和releaseAxis()。
[read-only] selectedSeries : QScatter3DSeries*
该属性存储所选系列或 null。
访问函数：
| QScatter3DSeries * | selectedSeries() const |
通知信号：
| void | selectedSeriesChanged(QScatter3DSeries *series) |
成员函数文档
[explicit] Q3DScatterWidgetItem::Q3DScatterWidgetItem(QObject *parent = nullptr)
使用可选参数parent 创建一个新的3D散点图。
[override virtual noexcept] Q3DScatterWidgetItem::~Q3DScatterWidgetItem()
删除该3D散点图。
void Q3DScatterWidgetItem::addAxis(QValue3DAxis *axis)
将axis 添加到图形中。通过addAxis添加的坐标轴尚未被实际使用，addAxis仅用于将axis 的所有权分配给该图形。axis 不能为空，也不能已被添加到其他图形中。
另请参阅 releaseAxis()、setAxisX()、setAxisY() 和setAxisZ()。
void Q3DScatterWidgetItem::addSeries(QScatter3DSeries *series)
将series 添加到图表中。一个图表可以包含多个系列，但只有一组坐标轴。如果新添加的系列指定了选定项，该项将被高亮显示，且任何现有的选择都将被清除。仅有一个新添加的系列可以处于活动选择状态。
另请参阅 Q3DGraphsWidgetItem::hasSeries()。
QList<QValue3DAxis *> Q3DScatterWidgetItem::axes() const
返回所有已添加坐标轴的列表。
另请参阅 addAxis()。
void Q3DScatterWidgetItem::releaseAxis(QValue3DAxis *axis)
如果该axis 已被添加到此图中，则将其所有权交还给调用方。如果被释放的axis 正在被使用，则会创建一个新的默认轴并将其设为活动状态。
如果默认轴已被释放，随后又被重新添加，其行为将与任何其他轴相同。
另请参阅 addAxis()、setAxisX()、setAxisY() 以及setAxisZ()。
void Q3DScatterWidgetItem::removeSeries(QScatter3DSeries *series)
从图中移除series 。
另请参阅 Q3DGraphsWidgetItem::hasSeries()。
QList<QScatter3DSeries *> Q3DScatterWidgetItem::seriesList() const
返回已添加到该图表的系列列表。
另请参阅 Q3DGraphsWidgetItem::hasSeries()。
© 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.
