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

Scatter3D QML Type

3D散点图。更多...

Import Statement: import QtGraphs
Inherits:

GraphsItem3D

属性

信号

方法

详细说明

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

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

import QtGraphs

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

import QtQuick
import QtGraphs

Item {
    width: 640
    height: 480

    Scatter3D {
        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 、Bars3D 、Surface3D 以及Qt Graphs 等用于 3D 渲染的 C++ 类。

属性文档

ambientLightStrength : real

整个图表的环境光强度。该值决定了无论光源位置如何，图表中各处的颜色显示是否均匀且明亮。该值必须在0.0 和1.0 之间。

aspectRatio : real

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

注意：此设置 对Bars3D 无影响。

另请参阅 horizontalAspectRatio 。

axisX : Value3DAxis

活动 x 轴。

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

axisY : Value3DAxis

活动 y 轴。

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

axisZ : Value3DAxis

当前活动的 Z 轴。

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

cameraPreset : Graphs3D.CameraPreset

当前激活的相机预设，该预设属于Graphs3D.CameraPreset 之一。如果未激活任何预设，则该值为Graphs3D.CameraPreset.NoPreset 。

cameraTargetPosition : vector3d

摄像机目标作为一个 Vector3d 对象。默认值为vector3d(0.0, 0.0, 0.0) 。

有效的坐标值范围为-1.0...1.0 ，其中边界值表示相应轴范围的边界。超出此范围的任何值都会被限制在边界内。

cameraXRotation : real

相机以目标点为轴，从当前基准位置开始的X轴旋转角度（单位：度）。

cameraYRotation : real

相机以目标点为轴，从当前基准位置开始的Y轴旋转角度（单位：度）。

cameraZoomLevel : real

摄像机的缩放级别（以百分比表示）。默认值100.0 表示摄像机未设置任何缩放。该值受minCameraZoomLevel 和maxCameraZoomLevel 属性的限制。

另请参阅 minCameraZoomLevel 和maxCameraZoomLevel 。

currentFps : int

启用帧率（FPS）测量功能后，过去一秒的测量结果将存储在此只读属性中。在测量功能激活后，该值至少需要一秒钟才会更新。

另请参阅 measureFps 。

customItemList : list<Custom3DItem>

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

cutoffMargin : real [since 6.11]

用于确定轴限值与图表元素被剔除的位置之间差值的数值。

注意：不 影响条形图。

该属性自 Qt 6.11 起引入。

dragMode : Graphs3D.DragMode [since 6.12]

确定如何解释图形上的拖动事件，取值范围为 Graphs3D.DragMode 枚举中的一个值。

默认值为Graphs3D.DragMode.Rotate 。

该属性在 Qt 6.12 中引入。

另请参阅 panEnabled 。

gridLineType : Graphs3D.GridLineType

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

此值将影响所有网格线。

另请参阅 Graphs3D.GridLineType 。

horizontalAspectRatio : real

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

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

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

labelMargin : real

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

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

另请参阅 QAbstract3DAxis::labelAutoAngle 。

lightColor : color

在Scene3D 中定义的环境光和镜面光颜色。

lightStrength : real

整个图形的镜面光强度。该值必须介于0.0 和10.0 之间。

该值会影响在Scene3D 中指定的光照效果。

locale : locale

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

另请参阅 Value3DAxis::labelFormat 。

margin : real

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

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

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

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

maxCameraXRotation : real [since 6.9]

相机围绕目标点的最大X轴旋转角度（单位：度）。默认值为180.0

该属性自 Qt 6.9 起引入。

maxCameraYRotation : real [since 6.9]

相机围绕目标点的最大 Y 轴旋转角度（单位：度）。默认值为90.0

该属性自 Qt 6.9 起引入。

maxCameraZoomLevel : real

设置相机允许的最大缩放级别。如果新的最大级别低于现有的最小级别，则最小级别也会调整为新的最大级别。如果当前的cameraZoomLevel 超出新范围，它也会被相应调整。默认值为500.0f 。

另请参阅 cameraZoomLevel 和minCameraZoomLevel 。

measureFps : bool

如果设置为true ，则渲染将持续进行，而非按需进行，并且currentFps 属性的值也会随之更新。默认值为false 。

另请参阅 currentFps 。

minCameraXRotation : real [since 6.9]

相机围绕目标点进行X轴旋转的最小角度（单位：度）。默认值为-180.0

该属性自 Qt 6.9 起引入。

minCameraYRotation : real [since 6.9]

相机围绕目标点的最小Y轴旋转角度（单位：度）。默认值为0.0

该属性自 Qt 6.9 起引入。

minCameraZoomLevel : real

设置允许的最小相机缩放级别。如果新的最小级别高于现有的最大级别，则最大级别也会调整为新的最小级别。如果当前的cameraZoomLevel 超出了新范围，它也会随之调整。minCameraZoomLevel不能设置为低于1.0 。默认值为10.0 。

另请参阅 cameraZoomLevel 和maxCameraZoomLevel 。

msaaSamples : int

当renderingMode 为Indirect 时，多采样抗锯齿所使用的采样数即为该值。当renderingMode 为DirectToBackground 时，该属性值为只读，并返回窗口表面格式所指定的采样数。默认值为4 。

另请参阅 renderingMode 。

optimizationHint : Graphs3D.OptimizationHint

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

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

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

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

orthoProjection : bool

如果设置为true ，则将使用正交投影来显示图形。默认值为false 。

注意： 当设置为true 时，阴影 将被禁用。

panEnabled : bool [since 6.12]

该输入处理程序是否允许在图上平移。

默认值为true 。

该属性在 Qt 6.12 中引入。

polar : bool

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

默认值为false 。

另请参阅 orthoProjection 和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 。

renderingMode : Graphs3D.RenderingMode

图的渲染方式。默认值为Indirect 。

注意：设置 图表的antialiasing 属性不会产生任何效果。但是，如果当前的渲染模式使用了抗锯齿，则该属性会由图表自身自动设置。

另请参阅 msaaSamples 和Graphs3D.RenderingMode 。

rootNode : Node [read-only, since 6.9]

返回指向 3D 图根节点的指针。使用此属性可通过 `importScene` 将 3D 图注入到单独的 `View3D ` 中：

Bars3D {
  id: bars
}
View3D {
  importScene: bars.rootNode
}

该属性于 Qt 6.9 中引入。

另请参阅 View3D 。

rotationEnabled : bool

该输入处理程序是否允许图形旋转。

默认值为true 。

scene : Scene3D [read-only]

Scene3D 指针，可用于操作场景并访问场景元素。

该属性为只读属性。

selectedElement : Graphs3D.ElementType [read-only]

图中选中的元素。

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

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

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

selectedSeries : Scatter3DSeries [read-only]

所选系列或为空。

selectionEnabled : bool

该输入处理程序是否允许从图中进行选择。

默认值为true 。

selectionMode : Graphs3D.SelectionMode

图形中的活动选择模式。属于Graphs3D.SelectionFlag 枚举值之一。

seriesList : list<Scatter3DSeries> [default]

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

shadowQuality : Graphs3D.ShadowQuality

阴影质量。Graphs3D.ShadowQuality 枚举值之一。

shadowStrength : real

整个图形的阴影强度。数值越高，阴影越深。该值必须在0.0 到100.0 之间。

该值会影响在Scene3D 中指定的光照效果。

theme : GraphsTheme

图表的当前主题。

另请参阅 GraphsTheme 。

transparencyTechnique : Graphs3D.TransparencyTechnique [since 6.9]

指定要使用的透明度处理方式。默认值为Default 。渲染透明表面图时，请使用Approximate 或Accurate 。对于其他类型的图，应使用Default 。

常量描述
Default表示不使用与顺序无关的透明度技术。可提供最佳性能。当图表不包含透明度，或者条形图或散点图同时使用实例化（即optimizationHint 设置为 {QtGraphs3D::OptimizationHint::Default}）时，请使用此选项。
Approximate表示图将尝试近似实现与顺序无关的透明度。此方法比Accurate 更快，可在较旧的硬件上运行，但可能会产生不准确的结果。当需要与顺序无关的透明度，但性能开销必须低于使用精确的与顺序无关的透明度时，请使用此方法。
Accurate表示使用精确的顺序无关透明度。当需要完美的透明度渲染时使用。

该属性在 Qt 6.9 中引入。

wrapCameraXRotation : bool

X 轴旋转中最小值和最大值的处理方式。默认情况下，X 轴旋转会从最小值循环到最大值，再从最大值循环回最小值。

若设置为true ，相机的 X 轴旋转将从最小值循环到最大值，再从最大值循环回最小值。若设置为false ，相机的 X 轴旋转将限制在由最小值和最大值确定的扇区内。

wrapCameraYRotation : bool

Y 轴旋转中最小值和最大值的限制行为。默认情况下，Y 轴旋转在最小值和最大值之间受限，且不进行循环。

如果true ，摄像机的Y轴旋转将从最小值循环到最大值，再从最大值循环回最小值。如果false ，摄像机的Y轴旋转将限制在由最小值和最大值确定的扇区内。

zoomAtTargetEnabled : bool

是否应在缩放时更改摄像头目标，以便图表中被缩放的点在缩放后仍保持在原位置。

默认值为true 。

zoomEnabled : bool

该输入处理程序是否允许对图表进行缩放。

默认值为true 。

Signal 文档

axisXChanged(ValueAxis3D axis)

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

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

axisYChanged(ValueAxis3D axis)

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

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

axisZChanged(ValueAxis3D axis)

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

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

doubleTapped(QEventPoint eventPoint, Qt::MouseButton button)

当在短时间内连续轻点图形项两次时，会触发此信号。eventPoint 信号参数包含来自释放事件的关于被轻点位置的信息，而button 表示被点击的mouse button ，或在触摸屏上为NoButton 。

注意： 对应的处理程序 是onDoubleTapped 。

另请参阅 QEventPoint 、Qt::MouseButtons 和TapHandler::doubleTapped 。

dragged(QVector2D delta)

当执行捏合手势时，如果图形上点簇的平移位置发生变化，则会发出此信号。delta 向量表示平移位置的变化量。

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

另请参阅 PinchHandler::translationChanged 。

longPressed()

当“parent ”控件被按住的时间超过TapHandler::longPressThreshold 时，会发出此信号。

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

另请参阅 TapHandler::longPressed 。

mouseMove(QPoint mousePos)

当图对象接收到 mouseMove 事件时，会触发此信号。mousePos 值表示鼠标移动时的当前位置。

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

另请参阅 QQuickItem::mouseMoveEvent 。

pinch(qreal delta)

当执行捏合手势时，如果图表上的缩放因子发生变化，则会发出此信号。delta 值表示缩放因子的乘法变化量。

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

另请参阅 PinchHandler::scaleChanged 。

selectedSeriesChanged(Scatter3DSeries series)

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

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

tapped(QEventPoint eventPoint, Qt::MouseButton button)

当图形项被点击一次时，会发出此信号。eventPoint 信号参数包含来自释放事件的关于被点击点的信息，而button 表示被点击的mouse button ，或在触摸屏上为NoButton 。

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

另请参阅 QEventPoint 、Qt::MouseButtons 和TapHandler::singleTapped 。

wheel(QQuickWheelEvent *event)

每当图表接收到类型为QWheelEvent 的event 时，都会触发此信号：也就是说，每次滚轮移动或滚动手势更新时都会触发。

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

另请参阅 WheelEvent 和WheelHandler::wheel 。

方法文档

qsizetype addCustomItem(Custom3DItem item)

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

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

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

void addSeries(Scatter3DSeries series)

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

另请参阅 GraphsItem3D::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 。

另请参阅 GraphsItem3D::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 。

void setDefaultInputHandler()

* * @brief 恢复默认的输入处理机制。 * * 此方法将重新启用内部预定义的输入处理程序。 * 若先前已调用 *unsetDefaultInputHandler ，请使用此方法恢复默认行为。 *

另请参阅 unsetDefaultInputHandler()。

void setDragButton(Qt::MouseButtons button)

* * @brief 设置用于触发拖动事件的鼠标按钮。 * * 此方法允许将启动 * 拖动操作所需的鼠标按钮更改为button 。 * 默认值为Qt::RightButton 。

[since 6.12] void setPanButton(Qt::MouseButtons button)

* * * @brief 设置用于触发平移事件的鼠标按钮。 * * 此方法允许将启动 * 拖动操作所需的鼠标按钮更改为button 。 * 默认值为Qt::MiddleButton 。

该方法在 Qt 6.12 中引入。

void unsetDefaultDragHandler()

* * @brief 禁用默认的拖动事件处理程序。 * * 这会专门取消对拖动手势的内置响应。 * 如果您需要为拖动操作实现自定义处理程序，请使用此选项。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultInputHandler()

* * @brief 禁用默认输入处理机制。 * * 此方法将停用所有预定义的默认输入处理程序。 * 若要覆盖默认行为，请调用此方法。 *

另请参阅 unsetDefaultTapHandler()、unsetDefaultDragHandler()、unsetDefaultWheelHandler() 以及unsetDefaultPinchHandler()。

void unsetDefaultPinchHandler()

* * @brief 禁用默认的捏合手势处理程序。 * * 这会专门取消对捏合手势的内置响应。 * 用于实现自定义捏合手势处理程序。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultTapHandler()

* * @brief 禁用默认的点击事件处理程序。 * * 这会专门取消对点击或单击事件的内置响应， * 从而支持自定义点击处理逻辑。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultWheelHandler()

* * @brief 禁用默认的鼠标滚轮事件处理程序。 * * 这会专门取消对鼠标滚轮滚动操作的内置响应。 * 在实现自定义滚轮行为时使用此功能。 *

另请参阅 unsetDefaultInputHandler()。

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