Back to Qt.io
Contact Us Blog Download Qt
在本页

Surface3D QML Type

描述三维曲面图的用法。更多

Import Statement: import QtGraphs
Inherits:

GraphsItem3D

属性

信号

方法

详细说明

开发人员可以使用该类型通过Qt Quick 渲染三维曲面图。

您需要导入Qt Graphs 模块才能使用该类型：

import QtGraphs

之后，您就可以在 qml 文件中使用 Surface3D 了：

import QtQuick
import QtGraphs

Item {
    width: 640
    height: 480

    Surface3D {
        width: parent.width
        height: parent.height
        Surface3DSeries {
            itemLabelFormat: "Pop density at (@xLabel N, @zLabel E): @yLabel"
            ItemModelSurfaceDataProxy {
                itemModel: dataModel
                // Mapping model roles to surface series rows, columns, and values.
                rowRole: "longitude"
                columnRole: "latitude"
                yPosRole: "pop_density"
            }
        }

        onTapped: {
            // Disable the default input handler
            unsetDefaultTapHandler()
            // Implement own custom event handler
            console.log("Custom tap event handler")
        }
    }
    ListModel {
        id: dataModel
        ListElement{ longitude: "20"; latitude: "10"; pop_density: "4.75"; }
        ListElement{ longitude: "21"; latitude: "10"; pop_density: "3.00"; }
        ListElement{ longitude: "22"; latitude: "10"; pop_density: "1.24"; }
        ListElement{ longitude: "23"; latitude: "10"; pop_density: "2.53"; }
        ListElement{ longitude: "20"; latitude: "11"; pop_density: "2.55"; }
        ListElement{ longitude: "21"; latitude: "11"; pop_density: "2.03"; }
        ListElement{ longitude: "22"; latitude: "11"; pop_density: "3.46"; }
        ListElement{ longitude: "23"; latitude: "11"; pop_density: "5.12"; }
        ListElement{ longitude: "20"; latitude: "12"; pop_density: "1.37"; }
        ListElement{ longitude: "21"; latitude: "12"; pop_density: "2.98"; }
        ListElement{ longitude: "22"; latitude: "12"; pop_density: "3.33"; }
        ListElement{ longitude: "23"; latitude: "12"; pop_density: "3.23"; }
        ListElement{ longitude: "20"; latitude: "13"; pop_density: "4.34"; }
        ListElement{ longitude: "21"; latitude: "13"; pop_density: "3.54"; }
        ListElement{ longitude: "22"; latitude: "13"; pop_density: "1.65"; }
        ListElement{ longitude: "23"; latitude: "13"; pop_density: "2.67"; }
    }
}

请参阅Surface Graph Gallery获取更全面的使用示例。

另请参阅 Surface3DSeries,ItemModelSurfaceDataProxy,Bars3D,Scatter3D, 和Qt Graphs C++ 3D 类。

属性文档

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

摄像机目标的向量 3d。默认为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 中引入。

flipHorizontalGrid : bool

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

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

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" locale。

另请参阅 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 时将禁用阴影。

polar : bool

如果true ，水平轴将变为极轴。x 轴变为角度轴，z 轴变为径向轴。极轴模式不适用于条形图。

默认为false 。

另请参见 orthoProjection 和radialLabelOffset 。

queriedGraphPosition : vector3d [read-only]

此只读属性包含使用Scene3D::graphPositionQuery 查询的每个轴的最新图形位置值。这些值已归一化为[-1, 1] 。如果查询到的位置超出了图形边界，则该值将不会反映真实位置，而是[-1, 1] 范围外的某个未定义位置。在进行查询之前，该值都是未定义的。

没有一个正确的三维坐标与特定的屏幕位置相匹配，因此为了保持一致，查询总是针对图形周围的一个不可见方框的内侧进行。

注意： 条形图只允许在图形底层查询图形位置，因此条形图的 y 值始终为零，只能在包含图形底层的屏幕位置进行有效查询。

另请参见 Scene3D::graphPositionQuery 。

radialLabelOffset : real

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

另请参阅 polar 。

renderingMode : Graphs3D.RenderingMode

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

注意： 设置图形的antialiasing 属性没有任何作用。但是，如果当前渲染模式使用抗锯齿，则图形本身会设置该属性。

另请参阅 msaaSamples 和Graphs3D.RenderingMode 。

rootNode : Node [read-only, since 6.9]

返回指向三维图形根节点的指针。使用importScene 将三维图形注入单独的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 : Surface3DSeries [read-only]

所选系列或空。如果selectionMode 已设置MultiSeries 标志，则该属性将保存拥有所选点的系列。

selectionEnabled : bool

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

默认为true 。

selectionMode : Graphs3D.SelectionMode

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

seriesList : list<Surface3DSeries> [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 。

信号文档

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 。

flipHorizontalGridChanged(bool flip)

当flipHorizontalGrid 更改为flip 时会发出该信号。

注： 相应的处理程序是onFlipHorizontalGridChanged 。

longPressed()

当按下parent 项目并保持超过TapHandler::longPressThreshold 的时间时，将发出该信号。

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

另请参阅 TapHandler::longPressed 。

mouseMove(QPoint mousePos)

该信号在图形接收到 mouseMove 事件时发出。mousePos 值为鼠标移动时的位置。

注： 相应的处理程序是onMouseMove 。

另请参见 QQuickItem::mouseMoveEvent 。

pinch(qreal delta)

当执行捏合手势时，图形上的比例因子发生变化时，就会发出该信号。delta 值表示缩放比例的乘法变化。

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

另请参见 PinchHandler::scaleChanged 。

selectedSeriesChanged(Surface3DSeries series)

当selectedSeries 更改为series 时会发出该信号。

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

tapped(QEventPoint eventPoint, Qt::MouseButton button)

该信号在图形项被点击一次时发出。eventPoint 信号参数包含释放事件中关于被点击点的信息，button 是被点击的mouse button ，或触摸屏上的NoButton 。

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

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

wheel(QQuickWheelEvent *event)

每次图形接收到event 类型的QWheelEvent 时，即每次移动滚轮或更新滚动手势时，都会发出该信号。

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

另请参阅 WheelEvent 和WheelHandler::wheel 。

方法文档

qsizetype addCustomItem(Custom3DItem item)

向图表添加Custom3DItem item 。图形拥有添加项的所有权。

如果添加成功，则返回已添加项的索引；如果试图添加一个空项，则返回-1；如果试图添加一个已添加项，则返回该项的索引。

另请参阅 removeCustomItems()、removeCustomItem() 和removeCustomItemAt()。

void addSeries(Surface3DSeries 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(Surface3DSeries series)

从图表中删除series 。

另请参见 GraphsItem3D::hasSeries().

void removeSeries(Surface3DSeries series)

从图表中删除series 。

另请参见 GraphsItem3D::hasSeries().

[since 6.10] void renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType, QUrl filePath)

从index 的系列中导出 2d 切片，并将结果保存到指定filePath 的图像中。要导出所有序列，请将index 设置为-1。导出的切片包括行或列，由sliceType 在给定的requestedIndex 中定义。

此方法在 Qt 6.10 中引入。

Abstract3DAxis selectedAxis()

可用于在接收到带有任何标签类型的selectedElementChanged 信号后获取所选轴。选择有效期至下一个selectedElementChanged 信号发出。

返回选中的轴或空值。

另请参阅 selectedElement 。

Custom3DItem selectedCustomItem()

可用于在接收到selectedElementChanged 信号后获取所选的自定义项目，信号类型为ElementType.CustomItem 。项目的所有权仍归图表所有。选择有效期至下一个selectedElementChanged 信号发出为止。

返回选中的自定义项目或 null。

另请参阅 selectedElement 。

qsizetype selectedCustomItemIndex()

在接收到selectedElementChanged 信号（类型为ElementType.CustomItem ）后，可用于查询所选自定义项的索引。选择有效期至下一个selectedElementChanged 信号发出。

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

另请参阅 selectedElement 。

int selectedLabelIndex()

可用于在接收到selectedElementChanged 信号后查询所选标签的索引，标签类型不限。选择有效期至下一个selectedElementChanged 信号发出。

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

另请参阅 selectedElement 。

void setDefaultInputHandler()

* 恢复默认的输入处理机制。* 本方法重新激活内部预定义的输入处理程序。* 在之前调用 *unsetDefaultInputHandler 后，使用此方法恢复默认行为。*

另请参阅 unsetDefaultInputHandler() 。

void setDragButton(Qt::MouseButtons button)

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

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.