Back to Qt.io
Contact Us Blog Download Qt
本页内容

Scatter3DNode QML Type

3D散点图节点。更多...

Import Statement: import QtGraphs
Inherits:

GraphsNode

属性

信号

方法

详细说明

此类型允许开发者使用Qt Quick 在3D环境中渲染散点图节点。

要使用此类型，您需要导入Qt Graphs 模块：

import QtGraphs

之后，您可以在 QML 文件中使用 Scatter3DNode：

import QtQuick
import QtGraphs

View3D {
    width: 640
    height: 480

    Scatter3DNode {
        width: parent.width
        height: parent.height
        Scatter3DSeries {
            ItemModelScatterDataProxy {
                itemModel: dataModel
                // Mapping model roles to scatter series item coordinates.
                xPosRole: "xPos"
                yPosRole: "yPos"
                zPosRole: "zPos"
            }
        }
    }

    ListModel {
        id: dataModel
        ListElement{ xPos: "2.754"; yPos: "1.455"; zPos: "3.362"; }
        ListElement{ xPos: "3.164"; yPos: "2.022"; zPos: "4.348"; }
        ListElement{ xPos: "4.564"; yPos: "1.865"; zPos: "1.346"; }
        ListElement{ xPos: "1.068"; yPos: "1.224"; zPos: "2.983"; }
        ListElement{ xPos: "2.323"; yPos: "2.502"; zPos: "3.133"; }
    }
}

另请参阅 Scatter3DSeries 、Spline3DSeries 、ScatterDataProxy 、Bars3DNode 、Surface3DNode 以及Qt Graphs 中的 3D C++ 类。

属性文档

aspectRatio : real

图中水平平面上的最长轴与y轴之间的缩放比例。默认值为2.0 。

注意： 此设置对Bars3D无效 。

另请参阅 horizontalAspectRatio 。

axisX : Value3DAxis

活动 x 轴。

如果未指定坐标轴，系统将创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果明确将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

axisY : Value3DAxis

活动 y 轴。

如果未指定坐标轴，则会创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

axisZ : Value3DAxis

当前活动的 Z 轴。

如果未指定坐标轴，系统将创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

customItemList : list<Custom3DItem>

添加到图中的Custom3DItem 项的列表。图将接管这些已添加项的所有权。

gridLineType : Graphs3D.GridLineType

用于指定网格线类型是Graphs3D.GridLineType.Shader 还是Graphs3D.GridLineType.Geometry 。

此值将影响所有网格线。

另请参阅 Graphs3D.GridLineType 。

horizontalAspectRatio : real

x 轴与 z 轴之间图表缩放的比例。0.0 的值表示根据轴范围自动缩放。默认值为0.0 。

注意：此属性 对Bars3DNode无效 ，后者通过barThickness 和barSpacing 属性处理水平面的缩放。极坐标图也会忽略此属性。

另请参阅 aspectRatio 、polar 、Bars3DNode::barThickness 和Bars3DNode::barSpacing 。

labelMargin : real

此属性用于指定坐标轴标签的放置间距。

负值将标签放置在绘图区域内，而正值将标签放置在绘图区域外。当该值为负时，标签的自动旋转功能将被禁用。默认值为0.1

另请参阅 QAbstract3DAxis::labelAutoAngle 。

locale : locale

设置用于格式化各种数字标签的区域设置。默认使用"C" 区域设置。

另请参阅 Value3DAxis::labelFormat 。

margin : real

用于确定可绘制图形区域边缘与图形背景边缘之间留白区域的绝对值。

如果边距值为负数，则边距将自动确定，并可能根据数据系列中数据点的大小和图表类型而变化。如果图表的纵横比未从默认值进行更改，则该值将被解释为 y 轴范围的百分比。默认值为-1.0 。

注意：若 为散点图设置的 边距小于自动确定的边距，可能会导致图表边缘处的散点与图表背景重叠。

注意：在 散点图和曲面图中 ，如果边距相对于坐标轴标签的大小较小，则会调整坐标轴边缘标签的位置，以避免与相邻坐标轴的边缘标签重叠。

optimizationHint : Graphs3D.OptimizationHint

指定渲染优化时使用默认模式还是传统模式。

默认模式采用实例化渲染，在大多数系统上可在最佳性能水平下提供完整的功能集。静态模式可优化图渲染，非常适合大型且内容不变的数据集。但在数据动态变化和项目旋转时，其运行速度较慢。 选择操作未经过优化，因此不建议在海量数据集上使用静态模式。传统模式会单独渲染图形中的所有项，而不进行实例化。仅当默认模式无法正常工作时才应使用该模式，即目标系统不支持实例化时。默认值为Default 。

注意：在 某些环境下 ，使用静态优化的大型图可能无法渲染，因为所有项都是通过单个绘制调用渲染的，而不同的图形驱动程序对每次调用的最大顶点数支持不同。这主要出现在 32 位和 OpenGL ES2 平台上。 要解决此问题，请选择顶点数较少的项网格，或使用点网格。

另请参阅 Abstract3DSeries::mesh 和Graphs3D.OptimizationHint 。

polar : bool

如果设置true ，则横轴将变为极坐标轴。x轴变为角轴，z轴变为半径轴。条形图不支持极坐标模式。

默认值为false 。

另请参阅 radialLabelOffset 。

queriedGraphPosition : vector3d [read-only]

此只读属性包含通过Scene3D::graphPositionQuery 查询得到的、沿各轴的最新图表位置值。这些值已归一化至[-1, 1] 的范围。如果查询的位置超出图表边界，则这些值不会反映实际位置，而是会显示为[-1, 1] 范围之外的某个未定义位置。在进行查询之前，该值将保持未定义状态。

由于不存在与特定屏幕位置完全对应的单一正确 3D 坐标，因此为了保持一致性，查询始终针对包围图表的不可见矩形的内侧进行。

注意：条形图 仅允许在图表底部高度处查询位置，因此条形图的 y 值始终为零，且仅当屏幕位置包含图表底部时，才能进行有效的查询。

另请参阅 Scene3D::graphPositionQuery 。

radialLabelOffset : real

该属性指定径向极坐标轴轴标注的归一化水平偏移量。值为0.0 时，表示轴标注应绘制在0角的角轴网格线旁。值为1.0 时，表示轴标注绘制在其通常位置，即图表背景的边缘。如果polar属性的值为false ，则该属性将被忽略。默认值为1.0 。

另请参阅 polar 。

selectedElement : Graphs3D.ElementType [read-only]

图中选中的元素。

该属性可用于查询所选元素的类型。该类型在图表中进行新选择并发出selectedElementChanged 信号之前一直有效。

该信号可用于实现自定义输入处理，例如“Axis Handling”示例中所示。

另请参阅 selectedLabelIndex()、selectedAxis()、selectedCustomItemIndex()、selectedCustomItem()、Bars3DNode::selectedSeries 、Scatter3DNode::selectedSeries 、Scene3D::selectionQueryPosition 以及Graphs3D.ElementType 。

selectedSeries : Scatter3DSeries [read-only]

所选系列或为空。

selectionMode : Graphs3D.SelectionMode

图形中的活动选择模式。graphs3d.selectionflag 枚举值之一。

seriesList : list<Scatter3DSeries> [default]

该属性用于存储图中的系列。默认情况下，该属性包含一个空列表。要设置系列，可以使用addSeries()方法，或者将其定义为图的子元素。

theme : GraphsTheme

图表的当前主题。

另请参阅 GraphsTheme 。

Signal 文档

axisXChanged(ValueAxis3D axis)

当axisX 变为axis 时，会触发此信号。

注意： 相应的处理程序 是onAxisXChanged 。

axisYChanged(ValueAxis3D axis)

当axisY 变为axis 时，会发出此信号。

注意： 相应的处理程序 为onAxisYChanged 。

axisZChanged(ValueAxis3D axis)

当axisZ 变为axis 时，会触发此信号。

注意： 相应的处理程序 是onAxisZChanged 。

selectedSeriesChanged(Scatter3DSeries series)

当selectedSeries 变为series 时，会触发此信号。

注意： 相应的处理程序 为onSelectedSeriesChanged 。

方法文档

qsizetype addCustomItem(Custom3DItem item)

向图中添加一个Custom3DItem item 。图将拥有该添加项的所有权。

若添加成功，则返回所添加项的索引；若尝试添加空项，则返回 -1；若尝试添加已存在的项，则返回该项的索引。

另请参阅 removeCustomItems()、removeCustomItem()，以及removeCustomItemAt()。

void addSeries(Scatter3DSeries series)

将series 添加到图表中。一个图表可以包含多个系列，但仅有一组坐标轴。如果新添加的系列指定了选定项，该项将被高亮显示，且任何现有的选定状态都将被清除。仅有一个新添加的系列可以处于选定状态。

另请参阅 GraphsNode::hasSeries()。

void clearSelection()

清除所有关联系列中的选中项。

void doPicking(QPoint point)

使用来自point 的视图坐标对图中的元素进行点选操作，并选择首个被击中的项目。默认的输入处理机制会在接收到 onTapped 事件时执行此操作。

另请参阅 selectedElement 。

void doRayPicking(QVector3D origin, QVector3D direction)

从origin 开始，在direction 中对图的元素执行拣选操作，并选择第一个匹配的项目。

另请参见 selectedElement 。

bool hasSeries(Abstract3DSeries series)

返回“series ”是否已添加到图中。

void releaseCustomItem(Custom3DItem item)

取回item 的所有权，并将item 从图中移除。

注意：如果 将同一项重新添加到图形中，则需要重新设置纹理文件。

另请参阅 Custom3DItem::textureFile 。

void removeCustomItem(Custom3DItem item)

删除自定义item 。并删除分配给该 的资源。

void removeCustomItemAt(vector3d position)

删除position 下的所有自定义项目。并释放分配给这些项目的资源。

void removeCustomItems()

删除所有自定义项目。并释放分配给它们的资源。

void removeSeries(Scatter3DSeries series)

从图中移除series 。

另请参阅 GraphsNode::hasSeries()。

Abstract3DAxis selectedAxis()

可用于在接收到selectedElementChanged 信号后获取所选轴，该信号的标签类型不限。该选择状态有效直至接收到下一个selectedElementChanged 信号。

返回所选轴，或返回 null。

另请参阅 selectedElement 。

Custom3DItem selectedCustomItem()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于获取所选的自定义项。该项的所有权仍归图所有。选中状态有效直至下一个selectedElementChanged 信号触发。

返回所选的自定义项，或 null。

另请参阅 selectedElement 。

qsizetype selectedCustomItemIndex()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于查询所选自定义项的索引。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选自定义项的索引，或 -1。

另请参阅 selectedElement 。

int selectedLabelIndex()

可在接收到selectedElementChanged 信号后，用于查询所选标签的索引，支持任何标签类型。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选标签的索引，或 -1。

另请参阅 selectedElement 。

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